@voodocs/cli 0.1.0

package/lib/darkarts/parsers/typescript/src/parser.ts

@@ -0,0 +1,408 @@
+/**
+ * TypeScript/JavaScript Parser for DarkArts Annotations
+ * 
+ * This parser uses the TypeScript Compiler API to extract @voodocs
+ * annotations from TypeScript and JavaScript files.
+ */
+
+import * as ts from 'typescript';
+import * as fs from 'fs';
+import * as path from 'path';
+
+interface Annotation {
+  [key: string]: any;
+}
+
+interface FunctionInfo {
+  name: string;
+  line: number;
+  parameters: string[];
+  return_type: string | null;
+  annotations: Annotation;
+  is_async: boolean;
+  is_exported: boolean;
+}
+
+interface ClassInfo {
+  name: string;
+  line: number;
+  annotations: Annotation;
+  methods: FunctionInfo[];
+  is_exported: boolean;
+}
+
+interface ParseResult {
+  file_path: string;
+  language: string;
+  module_annotations: Annotation;
+  classes: ClassInfo[];
+  functions: FunctionInfo[];
+  interfaces: InterfaceInfo[];
+}
+
+interface InterfaceInfo {
+  name: string;
+  line: number;
+  annotations: Annotation;
+  is_exported: boolean;
+}
+
+export class TypeScriptAnnotationParser {
+  private sourceFile: ts.SourceFile;
+  private sourceText: string;
+
+  constructor(private filePath: string) {
+    this.sourceText = fs.readFileSync(filePath, 'utf-8');
+    this.sourceFile = ts.createSourceFile(
+      filePath,
+      this.sourceText,
+      ts.ScriptTarget.Latest,
+      true
+    );
+  }
+
+  /**
+   * Parse the TypeScript file and extract all @voodocs annotations
+   */
+  public parse(): ParseResult {
+    const result: ParseResult = {
+      file_path: this.filePath,
+      language: this.filePath.endsWith('.ts') ? 'typescript' : 'javascript',
+      module_annotations: this.extractModuleAnnotations(),
+      classes: [],
+      functions: [],
+      interfaces: []
+    };
+
+    // Visit all nodes in the AST
+    const visit = (node: ts.Node) => {
+      if (ts.isClassDeclaration(node)) {
+        const classInfo = this.parseClass(node);
+        if (classInfo) {
+          result.classes.push(classInfo);
+        }
+      } else if (ts.isFunctionDeclaration(node)) {
+        const funcInfo = this.parseFunction(node);
+        if (funcInfo) {
+          result.functions.push(funcInfo);
+        }
+      } else if (ts.isInterfaceDeclaration(node)) {
+        const interfaceInfo = this.parseInterface(node);
+        if (interfaceInfo) {
+          result.interfaces.push(interfaceInfo);
+        }
+      }
+
+      ts.forEachChild(node, visit);
+    };
+
+    visit(this.sourceFile);
+
+    return result;
+  }
+
+  /**
+   * Extract module-level annotations from the top of the file
+   */
+  private extractModuleAnnotations(): Annotation {
+    const leadingComments = this.getLeadingComments(this.sourceFile);
+    for (const comment of leadingComments) {
+      if (this.isDarkArtsComment(comment)) {
+        return this.parseAnnotationText(comment);
+      }
+    }
+    return {};
+  }
+
+  /**
+   * Parse a class declaration
+   */
+  private parseClass(node: ts.ClassDeclaration): ClassInfo | null {
+    const name = node.name?.text;
+    if (!name) return null;
+
+    const line = this.getLineNumber(node);
+    const annotations = this.extractAnnotations(node);
+    const methods: FunctionInfo[] = [];
+
+    // Extract methods
+    node.members.forEach(member => {
+      if (ts.isMethodDeclaration(member)) {
+        const methodInfo = this.parseMethod(member);
+        if (methodInfo) {
+          methods.push(methodInfo);
+        }
+      }
+    });
+
+    return {
+      name,
+      line,
+      annotations,
+      methods,
+      is_exported: this.isExported(node)
+    };
+  }
+
+  /**
+   * Parse a function declaration
+   */
+  private parseFunction(node: ts.FunctionDeclaration): FunctionInfo | null {
+    const name = node.name?.text;
+    if (!name) return null;
+
+    return {
+      name,
+      line: this.getLineNumber(node),
+      parameters: this.extractParameters(node),
+      return_type: this.extractReturnType(node),
+      annotations: this.extractAnnotations(node),
+      is_async: this.isAsync(node),
+      is_exported: this.isExported(node)
+    };
+  }
+
+  /**
+   * Parse a method declaration
+   */
+  private parseMethod(node: ts.MethodDeclaration): FunctionInfo | null {
+    const name = (node.name as ts.Identifier).text;
+    if (!name) return null;
+
+    return {
+      name,
+      line: this.getLineNumber(node),
+      parameters: this.extractParameters(node),
+      return_type: this.extractReturnType(node),
+      annotations: this.extractAnnotations(node),
+      is_async: this.isAsync(node),
+      is_exported: false // Methods are not directly exported
+    };
+  }
+
+  /**
+   * Parse an interface declaration
+   */
+  private parseInterface(node: ts.InterfaceDeclaration): InterfaceInfo | null {
+    const name = node.name.text;
+    if (!name) return null;
+
+    return {
+      name,
+      line: this.getLineNumber(node),
+      annotations: this.extractAnnotations(node),
+      is_exported: this.isExported(node)
+    };
+  }
+
+  /**
+   * Extract annotations from a node's JSDoc comments
+   */
+  private extractAnnotations(node: ts.Node): Annotation {
+    const comments = this.getLeadingComments(node);
+    // Find the LAST (closest) @voodocs comment
+    let lastDarkArtsComment: string | null = null;
+    for (const comment of comments) {
+      if (this.isDarkArtsComment(comment)) {
+        lastDarkArtsComment = comment;
+      }
+    }
+    if (lastDarkArtsComment) {
+      return this.parseAnnotationText(lastDarkArtsComment);
+    }
+    return {};
+  }
+
+  /**
+   * Get leading comments for a node
+   */
+  private getLeadingComments(node: ts.Node): string[] {
+    const comments: string[] = [];
+    const fullText = this.sourceText;
+    const nodePos = node.getFullStart();
+    
+    const ranges = ts.getLeadingCommentRanges(fullText, nodePos);
+    if (ranges) {
+      for (const range of ranges) {
+        const commentText = fullText.substring(range.pos, range.end);
+        comments.push(commentText);
+      }
+    }
+
+    return comments;
+  }
+
+  /**
+   * Check if a comment contains @voodocs annotation
+   */
+  private isDarkArtsComment(comment: string): boolean {
+    return comment.includes('@voodocs');
+  }
+
+  /**
+   * Parse the annotation text and extract key-value pairs
+   */
+  private parseAnnotationText(comment: string): Annotation {
+    const annotation: Annotation = {};
+    
+    // Remove comment markers
+    let text = comment.replace(/^\/\*\*?|\*\/$/g, '').trim();
+    text = text.replace(/^\s*\*\s?/gm, ''); // Remove leading asterisks
+    
+    // Remove @voodocs marker
+    text = text.replace(/@voodocs\s*/i, '');
+    
+    // Parse key-value pairs
+    const lines = text.split('\n');
+    let currentKey: string | null = null;
+    let currentValue: string[] = [];
+    
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      
+      // Check if this is a new key
+      const keyMatch = trimmed.match(/^(\w+):\s*(.*)$/);
+      if (keyMatch) {
+        // Save previous key-value pair
+        if (currentKey) {
+          annotation[currentKey] = this.parseValue(currentValue.join('\n'));
+        }
+        
+        currentKey = keyMatch[1];
+        currentValue = [keyMatch[2]];
+      } else if (currentKey) {
+        // Continue current value
+        currentValue.push(trimmed);
+      }
+    }
+    
+    // Save last key-value pair
+    if (currentKey) {
+      annotation[currentKey] = this.parseValue(currentValue.join('\n'));
+    }
+    
+    return annotation;
+  }
+
+  /**
+   * Parse a value (string, array, or object)
+   */
+  private parseValue(value: string): any {
+    value = value.trim();
+    
+    // Try to parse as JSON array
+    if (value.startsWith('[') && value.endsWith(']')) {
+      try {
+        // Extract array content
+        const content = value.slice(1, -1).trim();
+        if (!content) return [];
+        
+        // Split by newlines first (each line is typically one item)
+        const items: string[] = [];
+        let currentItem = '';
+        let inQuotes = false;
+        let quoteChar = '';
+        
+        for (let i = 0; i < content.length; i++) {
+          const char = content[i];
+          
+          if ((char === '"' || char === "'") && (i === 0 || content[i-1] !== '\\')) {
+            if (!inQuotes) {
+              inQuotes = true;
+              quoteChar = char;
+            } else if (char === quoteChar) {
+              inQuotes = false;
+            }
+          }
+          
+          if (char === ',' && !inQuotes) {
+            if (currentItem.trim()) {
+              items.push(currentItem.trim());
+            }
+            currentItem = '';
+          } else {
+            currentItem += char;
+          }
+        }
+        
+        // Add the last item
+        if (currentItem.trim()) {
+          items.push(currentItem.trim());
+        }
+        
+        // Clean up each item
+        return items.map(item => {
+          item = item.trim();
+          // Remove surrounding quotes
+          if ((item.startsWith('"') && item.endsWith('"')) ||
+              (item.startsWith("'") && item.endsWith("'"))) {
+            return item.slice(1, -1);
+          }
+          return item;
+        });
+      } catch (e) {
+        return value;
+      }
+    }
+    
+    // Remove quotes if present
+    if ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))) {
+      return value.slice(1, -1);
+    }
+    
+    return value;
+  }
+
+  /**
+   * Extract parameter names from a function/method
+   */
+  private extractParameters(node: ts.FunctionDeclaration | ts.MethodDeclaration): string[] {
+    return node.parameters.map(param => {
+      const name = (param.name as ts.Identifier).text;
+      const type = param.type ? `: ${param.type.getText(this.sourceFile)}` : '';
+      return `${name}${type}`;
+    });
+  }
+
+  /**
+   * Extract return type from a function/method
+   */
+  private extractReturnType(node: ts.FunctionDeclaration | ts.MethodDeclaration): string | null {
+    if (node.type) {
+      return node.type.getText(this.sourceFile);
+    }
+    return null;
+  }
+
+  /**
+   * Check if a function/method is async
+   */
+  private isAsync(node: ts.FunctionDeclaration | ts.MethodDeclaration): boolean {
+    if (ts.canHaveModifiers(node)) {
+      const modifiers = ts.getModifiers(node);
+      return modifiers?.some((m: ts.Modifier) => m.kind === ts.SyntaxKind.AsyncKeyword) || false;
+    }
+    return false;
+  }
+
+  /**
+   * Check if a node is exported
+   */
+  private isExported(node: ts.Node): boolean {
+    if (ts.canHaveModifiers(node)) {
+      const modifiers = ts.getModifiers(node);
+      return modifiers?.some((m: ts.Modifier) => m.kind === ts.SyntaxKind.ExportKeyword) || false;
+    }
+    return false;
+  }
+
+  /**
+   * Get the line number of a node
+   */
+  private getLineNumber(node: ts.Node): number {
+    const { line } = this.sourceFile.getLineAndCharacterOfPosition(node.getStart());
+    return line + 1; // Convert to 1-indexed
+  }
+}

package/lib/darkarts/parsers/typescript/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}