tlc-claude-code 0.9.7 → 0.9.8

package/server/lib/docs-command.js

@@ -0,0 +1,271 @@
+/**
+ * Docs Command Module
+ * CLI command handler for /tlc:docs
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { createDocsGenerator } = require('./docs-generator.js');
+
+/**
+ * Default output directory
+ */
+const DEFAULT_OUTPUT_DIR = 'docs/api';
+
+/**
+ * Simple glob implementation (no external deps)
+ * @param {string} pattern - Glob pattern
+ * @param {Object} options - Options
+ * @returns {Promise<Array>} Matching files
+ */
+async function simpleGlob(pattern, options = {}) {
+  const { cwd = process.cwd(), ignore = [] } = options;
+  const results = [];
+
+  // Convert glob pattern to regex
+  const regexPattern = pattern
+    .replace(/\*\*/g, '{{GLOBSTAR}}')
+    .replace(/\*/g, '[^/]*')
+    .replace(/\?/g, '.')
+    .replace(/{{GLOBSTAR}}/g, '.*')
+    .replace(/\{([^}]+)\}/g, (_, group) => `(${group.split(',').join('|')})`);
+
+  const regex = new RegExp(`^${regexPattern}$`);
+
+  function walkDir(dir, baseDir) {
+    try {
+      const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+      for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        const relativePath = path.relative(baseDir, fullPath).replace(/\\/g, '/');
+
+        // Check ignore patterns
+        const shouldIgnore = ignore.some(ig => {
+          if (ig.includes('**')) {
+            return relativePath.includes(ig.replace(/\*\*/g, ''));
+          }
+          return relativePath.includes(ig);
+        });
+
+        if (shouldIgnore) continue;
+
+        if (entry.isDirectory()) {
+          walkDir(fullPath, baseDir);
+        } else if (regex.test(relativePath)) {
+          results.push(relativePath);
+        }
+      }
+    } catch (error) {
+      // Skip unreadable directories
+    }
+  }
+
+  walkDir(cwd, cwd);
+  return results;
+}
+
+/**
+ * Format file size
+ * @param {number} bytes - File size in bytes
+ * @returns {string} Formatted size
+ */
+function formatSize(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+/**
+ * Run docs generation command
+ * @param {Object} options - Command options
+ * @returns {Object} Command result
+ */
+async function runDocsCommand(options = {}) {
+  const {
+    baseDir = process.cwd(),
+    outputDir = DEFAULT_OUTPUT_DIR,
+    format = 'both',
+    title = null,
+    version = null,
+    baseUrl = 'http://localhost:3000',
+    verbose = false,
+  } = options;
+
+  const result = {
+    success: false,
+    message: '',
+    files: [],
+    report: null,
+    errors: [],
+  };
+
+  try {
+    // Create generator
+    const generator = createDocsGenerator({ baseDir, baseUrl });
+
+    // Generate docs
+    const info = {};
+    if (title) info.title = title;
+    if (version) info.version = version;
+
+    const docs = await generator.generate({
+      baseDir,
+      globFn: simpleGlob,
+      info,
+      baseUrl,
+    });
+
+    // Check validation
+    if (!docs.validation.valid) {
+      result.errors = docs.validation.errors;
+      if (verbose) {
+        console.warn('Validation warnings:', docs.validation.warnings);
+      }
+    }
+
+    // Write output
+    const fullOutputDir = path.isAbsolute(outputDir)
+      ? outputDir
+      : path.join(baseDir, outputDir);
+
+    const writeResult = generator.write(docs, fullOutputDir, { format });
+
+    result.success = true;
+    result.files = writeResult.files;
+    result.report = docs.report;
+
+    // Build summary message
+    const parts = [];
+    parts.push(`Generated API documentation`);
+
+    if (docs.report.existingSpec) {
+      parts.push(`  Based on: ${path.basename(docs.report.existingSpec)}`);
+    }
+
+    parts.push(`  Routes: ${docs.report.totalRoutes} detected, ${docs.report.newRoutes} documented`);
+
+    if (docs.report.schemas > 0) {
+      parts.push(`  Schemas: ${docs.report.schemas} models`);
+    }
+
+    parts.push(`  Output: ${fullOutputDir}`);
+
+    for (const file of writeResult.files) {
+      const stats = fs.statSync(file);
+      parts.push(`    - ${path.basename(file)} (${formatSize(stats.size)})`);
+    }
+
+    result.message = parts.join('\n');
+
+  } catch (error) {
+    result.success = false;
+    result.message = `Documentation generation failed: ${error.message}`;
+    result.errors.push(error.message);
+  }
+
+  return result;
+}
+
+/**
+ * Parse command arguments
+ * @param {string} args - Command arguments string
+ * @returns {Object} Parsed options
+ */
+function parseArgs(args = '') {
+  const options = {};
+  const parts = args.split(/\s+/).filter(Boolean);
+
+  for (let i = 0; i < parts.length; i++) {
+    const part = parts[i];
+
+    if (part === '--output' || part === '-o') {
+      options.outputDir = parts[++i];
+    } else if (part === '--format' || part === '-f') {
+      options.format = parts[++i];
+    } else if (part === '--title' || part === '-t') {
+      options.title = parts[++i];
+    } else if (part === '--version' || part === '-v') {
+      options.version = parts[++i];
+    } else if (part === '--base-url' || part === '-b') {
+      options.baseUrl = parts[++i];
+    } else if (part === '--verbose') {
+      options.verbose = true;
+    } else if (part === '--help' || part === '-h') {
+      options.help = true;
+    }
+  }
+
+  return options;
+}
+
+/**
+ * Get help text
+ * @returns {string} Help text
+ */
+function getHelpText() {
+  return `
+/tlc:docs - Generate API Documentation
+
+Usage:
+  /tlc:docs [options]
+
+Options:
+  -o, --output <dir>     Output directory (default: docs/api)
+  -f, --format <type>    Output format: json, yaml, both (default: both)
+  -t, --title <name>     API title
+  -v, --version <ver>    API version
+  -b, --base-url <url>   Base URL (default: http://localhost:3000)
+  --verbose              Show detailed output
+  -h, --help             Show this help
+
+Examples:
+  /tlc:docs                           # Generate with defaults
+  /tlc:docs -o api-docs               # Custom output directory
+  /tlc:docs -f yaml -t "My API"       # YAML only with custom title
+  /tlc:docs -b https://api.example.com
+
+What it does:
+  1. Finds existing OpenAPI/Swagger specs (adopts them first)
+  2. Scans code for routes (Express, Fastify, Hono, Koa)
+  3. Parses ORM schemas (Drizzle, Prisma, TypeORM)
+  4. Generates OpenAPI 3.x specification
+  5. Creates curl examples and sample payloads
+  6. Merges detected routes into existing specs
+
+Output files:
+  - openapi.json / openapi.yaml - OpenAPI specification
+  - examples.json - Curl commands and sample payloads
+  - docs-report.json - Generation report
+`.trim();
+}
+
+/**
+ * Command entry point
+ * @param {string} args - Command arguments
+ * @returns {Promise<Object>} Command result
+ */
+async function docsCommand(args = '') {
+  const options = parseArgs(args);
+
+  if (options.help) {
+    return {
+      success: true,
+      message: getHelpText(),
+      files: [],
+      report: null,
+    };
+  }
+
+  return runDocsCommand(options);
+}
+
+module.exports = {
+  DEFAULT_OUTPUT_DIR,
+  simpleGlob,
+  formatSize,
+  runDocsCommand,
+  parseArgs,
+  getHelpText,
+  docsCommand,
+};

package/server/lib/docs-command.test.js

@@ -0,0 +1,269 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import fs from 'fs';
+import path from 'path';
+import {
+  DEFAULT_OUTPUT_DIR,
+  simpleGlob,
+  formatSize,
+  runDocsCommand,
+  parseArgs,
+  getHelpText,
+  docsCommand,
+} from './docs-command.js';
+
+describe('docs-command', () => {
+  describe('DEFAULT_OUTPUT_DIR', () => {
+    it('has default value', () => {
+      expect(DEFAULT_OUTPUT_DIR).toBe('docs/api');
+    });
+  });
+
+  describe('formatSize', () => {
+    it('formats bytes', () => {
+      expect(formatSize(500)).toBe('500 B');
+    });
+
+    it('formats kilobytes', () => {
+      expect(formatSize(2048)).toBe('2.0 KB');
+    });
+
+    it('formats megabytes', () => {
+      expect(formatSize(2 * 1024 * 1024)).toBe('2.0 MB');
+    });
+  });
+
+  describe('parseArgs', () => {
+    it('parses empty args', () => {
+      const options = parseArgs('');
+      expect(options).toEqual({});
+    });
+
+    it('parses output dir', () => {
+      expect(parseArgs('--output api-docs').outputDir).toBe('api-docs');
+      expect(parseArgs('-o api-docs').outputDir).toBe('api-docs');
+    });
+
+    it('parses format', () => {
+      expect(parseArgs('--format yaml').format).toBe('yaml');
+      expect(parseArgs('-f json').format).toBe('json');
+    });
+
+    it('parses title', () => {
+      expect(parseArgs('--title MyAPI').title).toBe('MyAPI');
+      expect(parseArgs('-t MyAPI').title).toBe('MyAPI');
+    });
+
+    it('parses version', () => {
+      expect(parseArgs('--version 2.0.0').version).toBe('2.0.0');
+      expect(parseArgs('-v 2.0.0').version).toBe('2.0.0');
+    });
+
+    it('parses base URL', () => {
+      expect(parseArgs('--base-url https://api.example.com').baseUrl).toBe('https://api.example.com');
+      expect(parseArgs('-b https://api.example.com').baseUrl).toBe('https://api.example.com');
+    });
+
+    it('parses verbose', () => {
+      expect(parseArgs('--verbose').verbose).toBe(true);
+    });
+
+    it('parses help', () => {
+      expect(parseArgs('--help').help).toBe(true);
+      expect(parseArgs('-h').help).toBe(true);
+    });
+
+    it('parses multiple options', () => {
+      const options = parseArgs('-o output -f yaml -t API -v 1.0.0');
+      expect(options.outputDir).toBe('output');
+      expect(options.format).toBe('yaml');
+      expect(options.title).toBe('API');
+      expect(options.version).toBe('1.0.0');
+    });
+  });
+
+  describe('getHelpText', () => {
+    it('returns help text', () => {
+      const help = getHelpText();
+      expect(help).toContain('/tlc:docs');
+      expect(help).toContain('--output');
+      expect(help).toContain('--format');
+      expect(help).toContain('Examples');
+    });
+
+    it('documents all options', () => {
+      const help = getHelpText();
+      expect(help).toContain('-o');
+      expect(help).toContain('-f');
+      expect(help).toContain('-t');
+      expect(help).toContain('-v');
+      expect(help).toContain('-b');
+      expect(help).toContain('-h');
+    });
+  });
+
+  describe('simpleGlob', () => {
+    it('returns empty for non-existent directory', async () => {
+      const results = await simpleGlob('**/*.js', { cwd: '/nonexistent-path-12345' });
+      expect(results).toEqual([]);
+    });
+  });
+
+  describe('docsCommand', () => {
+    it('returns help when --help flag', async () => {
+      const result = await docsCommand('--help');
+      expect(result.success).toBe(true);
+      expect(result.message).toContain('/tlc:docs');
+    });
+
+    it('returns help when -h flag', async () => {
+      const result = await docsCommand('-h');
+      expect(result.success).toBe(true);
+      expect(result.message).toContain('Usage');
+    });
+  });
+
+  describe('runDocsCommand', () => {
+    const testDir = '/tmp/tlc-docs-test-' + Date.now();
+
+    beforeEach(() => {
+      if (!fs.existsSync(testDir)) {
+        fs.mkdirSync(testDir, { recursive: true });
+      }
+    });
+
+    afterEach(() => {
+      try {
+        fs.rmSync(testDir, { recursive: true, force: true });
+      } catch (e) {
+        // Ignore cleanup errors
+      }
+    });
+
+    it('generates docs in output directory', async () => {
+      const outputDir = path.join(testDir, 'api-docs');
+
+      const result = await runDocsCommand({
+        baseDir: testDir,
+        outputDir,
+      });
+
+      expect(result.success).toBe(true);
+      expect(result.files.length).toBeGreaterThan(0);
+      expect(fs.existsSync(outputDir)).toBe(true);
+    });
+
+    it('creates openapi.json', async () => {
+      const outputDir = path.join(testDir, 'docs');
+
+      await runDocsCommand({
+        baseDir: testDir,
+        outputDir,
+        format: 'json',
+      });
+
+      expect(fs.existsSync(path.join(outputDir, 'openapi.json'))).toBe(true);
+    });
+
+    it('creates openapi.yaml', async () => {
+      const outputDir = path.join(testDir, 'docs');
+
+      await runDocsCommand({
+        baseDir: testDir,
+        outputDir,
+        format: 'yaml',
+      });
+
+      expect(fs.existsSync(path.join(outputDir, 'openapi.yaml'))).toBe(true);
+    });
+
+    it('creates examples.json', async () => {
+      const outputDir = path.join(testDir, 'docs');
+
+      await runDocsCommand({
+        baseDir: testDir,
+        outputDir,
+      });
+
+      expect(fs.existsSync(path.join(outputDir, 'examples.json'))).toBe(true);
+    });
+
+    it('creates docs-report.json', async () => {
+      const outputDir = path.join(testDir, 'docs');
+
+      await runDocsCommand({
+        baseDir: testDir,
+        outputDir,
+      });
+
+      expect(fs.existsSync(path.join(outputDir, 'docs-report.json'))).toBe(true);
+    });
+
+    it('uses custom title', async () => {
+      const outputDir = path.join(testDir, 'docs');
+
+      await runDocsCommand({
+        baseDir: testDir,
+        outputDir,
+        title: 'My Custom API',
+        format: 'json',
+      });
+
+      const spec = JSON.parse(fs.readFileSync(path.join(outputDir, 'openapi.json'), 'utf-8'));
+      expect(spec.info.title).toBe('My Custom API');
+    });
+
+    it('uses custom version', async () => {
+      const outputDir = path.join(testDir, 'docs');
+
+      await runDocsCommand({
+        baseDir: testDir,
+        outputDir,
+        version: '2.5.0',
+        format: 'json',
+      });
+
+      const spec = JSON.parse(fs.readFileSync(path.join(outputDir, 'openapi.json'), 'utf-8'));
+      expect(spec.info.version).toBe('2.5.0');
+    });
+
+    it('uses custom base URL', async () => {
+      const outputDir = path.join(testDir, 'docs');
+
+      await runDocsCommand({
+        baseDir: testDir,
+        outputDir,
+        baseUrl: 'https://api.example.com',
+        format: 'json',
+      });
+
+      const spec = JSON.parse(fs.readFileSync(path.join(outputDir, 'openapi.json'), 'utf-8'));
+      expect(spec.servers[0].url).toBe('https://api.example.com');
+    });
+
+    it('returns report with stats', async () => {
+      const outputDir = path.join(testDir, 'docs');
+
+      const result = await runDocsCommand({
+        baseDir: testDir,
+        outputDir,
+      });
+
+      expect(result.report).toBeDefined();
+      expect(result.report.totalRoutes).toBeDefined();
+      expect(result.report.routeFiles).toBeDefined();
+    });
+
+    it('includes message with summary', async () => {
+      const outputDir = path.join(testDir, 'docs');
+
+      const result = await runDocsCommand({
+        baseDir: testDir,
+        outputDir,
+      });
+
+      expect(result.message).toContain('Generated');
+      expect(result.message).toContain('Routes');
+      expect(result.message).toContain('Output');
+    });
+  });
+});