@principal-ai/codebase-composition 0.1.0

package/src/modules/__fixtures__/typescript-packages/simple-types/index.ts

@@ -0,0 +1,53 @@
+/**
+ * User interface for testing
+ * @description Represents a user in the system
+ */
+export interface User {
+  id: string;
+  name: string;
+  email: string;
+  age?: number;
+}
+
+/**
+ * Status type for testing union types
+ */
+export type Status = 'active' | 'inactive' | 'pending';
+
+/**
+ * UserProfile class for testing class extraction
+ */
+export class UserProfile {
+  constructor(
+    public user: User,
+    public status: Status,
+  ) {}
+
+  getDisplayName(): string {
+    return this.user.name;
+  }
+
+  isActive(): boolean {
+    return this.status === 'active';
+  }
+}
+
+/**
+ * Action enum for testing enum extraction
+ */
+export enum Action {
+  CREATE = 'create',
+  UPDATE = 'update',
+  DELETE = 'delete',
+  READ = 'read',
+}
+
+/**
+ * Utility function for testing function extraction
+ */
+export function formatUser(user: User): string {
+  return `${user.name} <${user.email}>`;
+}
+
+// Default export
+export default UserProfile;

package/src/modules/__fixtures__/typescript-packages/simple-types/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "simple-types-test",
+  "version": "1.0.0",
+  "main": "index.ts",
+  "types": "index.ts"
+}

package/src/modules/extractors/README.md

@@ -0,0 +1,55 @@
+# Type Extractors
+
+This directory contains language-specific type extractors that implement the `TypeExtractor` interface.
+
+## Current Extractors
+
+### TypeScriptExtractor
+
+- **Language**: TypeScript/JavaScript
+- **File Extensions**: `.ts`, `.tsx`
+- **Features**:
+  - Extracts interfaces, types, classes, enums, functions
+  - Supports JSDoc comments
+  - Handles default and named exports
+  - Generates TypeScript definition files
+
+## Adding New Extractors
+
+To add support for a new language, implement the `TypeExtractor` interface:
+
+```typescript
+import { TypeExtractor, PackageTypes } from '../../types/layer-types';
+
+export class PythonExtractor implements TypeExtractor {
+  name = 'Python';
+
+  canHandle(packagePath: string, fileExtensions: string[]): boolean {
+    return fileExtensions.includes('.py');
+  }
+
+  async extractTypes(packagePath: string, options?: any): Promise<PackageTypes> {
+    // Use Python AST or tools like mypy to extract type information
+    // Return PackageTypes with extracted Python types
+  }
+
+  async generateDefinitionFile?(packageTypes: PackageTypes): Promise<string> {
+    // Generate .pyi stub files
+  }
+}
+```
+
+Then register it with the TypeExtractionModule:
+
+```typescript
+const extractor = new TypeExtractionModule();
+extractor.registerExtractor(new PythonExtractor());
+```
+
+## Architecture Benefits
+
+- **Language Agnostic**: Core system works with any language
+- **Extensible**: Easy to add new languages
+- **Consistent API**: All extractors provide the same interface
+- **Registry Pattern**: Dynamic extractor discovery and registration
+- **Future-Proof**: Ready for Go, Java, C#, etc.

package/src/modules/extractors/TypeScriptExtractor.ts

@@ -0,0 +1,409 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+import * as ts from 'typescript';
+
+import { TypeExtractor, ExtractedType, PackageTypes } from '../../types/layer-types';
+
+export interface TypeScriptExtractionOptions {
+  includeTests?: boolean;
+  includeInternal?: boolean;
+}
+
+export class TypeScriptExtractor implements TypeExtractor {
+  name = 'TypeScript';
+
+  canHandle(packagePath: string, fileExtensions: string[]): boolean {
+    // Check if package contains TypeScript files
+    return fileExtensions.some(ext => ['.ts', '.tsx'].includes(ext));
+  }
+
+  async extractTypes(
+    packagePath: string,
+    options: TypeScriptExtractionOptions = {},
+  ): Promise<PackageTypes> {
+    console.log(`[TypeScriptExtractor] Extracting types from package path: ${packagePath}`);
+
+    // Verify package path exists
+    if (!fs.existsSync(packagePath)) {
+      throw new Error(`Package path does not exist: ${packagePath}`);
+    }
+
+    // Read package.json to get package name
+    const packageJsonPath = path.join(packagePath, 'package.json');
+    let packageName = path.basename(packagePath);
+
+    try {
+      const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+      packageName = packageJson.name || packageName;
+    } catch (error) {
+      console.log(`[TypeScriptExtractor] Could not read package.json: ${error}`);
+    }
+
+    // Find all TypeScript files in the package
+    const tsFiles = this.findTypeScriptFiles(packagePath, options);
+
+    if (tsFiles.length === 0) {
+      return {
+        packagePath,
+        packageName,
+        types: [],
+        exports: { named: [] },
+      };
+    }
+
+    // Create a TypeScript program
+    const compilerOptions: ts.CompilerOptions = {
+      target: ts.ScriptTarget.ES2020,
+      module: ts.ModuleKind.CommonJS,
+      lib: ['es2020'],
+      declaration: true,
+      emitDeclarationOnly: true,
+      skipLibCheck: true,
+      allowJs: false,
+      resolveJsonModule: true,
+      esModuleInterop: true,
+      strict: true,
+    };
+
+    const program = ts.createProgram(tsFiles, compilerOptions);
+    const checker = program.getTypeChecker();
+    const extractedTypes: ExtractedType[] = [];
+    const exportedNames = new Set<string>();
+    const defaultExport: { value?: string } = {};
+
+    // Process each source file
+    for (const sourceFile of program.getSourceFiles()) {
+      if (sourceFile.isDeclarationFile) continue;
+      if (!sourceFile.fileName.startsWith(packagePath)) continue;
+
+      // Visit each node in the source file
+      ts.forEachChild(sourceFile, node => {
+        this.visitNode(
+          node,
+          sourceFile,
+          checker,
+          extractedTypes,
+          exportedNames,
+          defaultExport,
+          packagePath,
+        );
+      });
+    }
+
+    // Sort types by kind and name
+    extractedTypes.sort((a, b) => {
+      const kindOrder = ['interface', 'type', 'class', 'enum', 'function'];
+      const aOrder = kindOrder.indexOf(a.kind);
+      const bOrder = kindOrder.indexOf(b.kind);
+      if (aOrder !== bOrder) return aOrder - bOrder;
+      return a.name.localeCompare(b.name);
+    });
+
+    return {
+      packagePath,
+      packageName,
+      types: extractedTypes,
+      exports: {
+        named: Array.from(exportedNames),
+        default: defaultExport.value,
+      },
+    };
+  }
+
+  async generateDefinitionFile(packageTypes: PackageTypes): Promise<string> {
+    const lines: string[] = [];
+
+    // Add header
+    lines.push(`// Type definitions for ${packageTypes.packageName}`);
+    lines.push(`// Generated from: ${packageTypes.packagePath}`);
+    lines.push(`// Generated on: ${new Date().toISOString()}`);
+    lines.push('');
+
+    // Group types by kind
+    const typesByKind = packageTypes.types.reduce(
+      (acc, type) => {
+        if (!acc[type.kind]) acc[type.kind] = [];
+        acc[type.kind].push(type);
+        return acc;
+      },
+      {} as Record<string, ExtractedType[]>,
+    );
+
+    // Add types in order
+    const kinds = ['interface', 'type', 'class', 'enum', 'function'] as const;
+    for (const kind of kinds) {
+      const types = typesByKind[kind];
+      if (!types || types.length === 0) continue;
+
+      lines.push(`// ${kind.charAt(0).toUpperCase() + kind.slice(1)}s`);
+      lines.push('');
+
+      for (const type of types) {
+        if (type.jsDoc) {
+          lines.push(`/** ${type.jsDoc} */`);
+        }
+        if (type.isExported) {
+          // Remove existing 'export' keyword if present to avoid duplication
+          const cleanText = type.text.replace(/^export\s+/, '');
+          lines.push(`export ${cleanText}`);
+        } else {
+          lines.push(type.text);
+        }
+        lines.push('');
+      }
+    }
+
+    return lines.join('\n');
+  }
+
+  private findTypeScriptFiles(dir: string, options: TypeScriptExtractionOptions = {}): string[] {
+    const files: string[] = [];
+
+    const walk = (currentDir: string) => {
+      try {
+        const entries = fs.readdirSync(currentDir, { withFileTypes: true });
+
+        for (const entry of entries) {
+          const fullPath = path.join(currentDir, entry.name);
+
+          if (entry.isDirectory()) {
+            // Skip node_modules and hidden directories
+            if (entry.name !== 'node_modules' && !entry.name.startsWith('.')) {
+              walk(fullPath);
+            }
+          } else if (entry.isFile()) {
+            if (entry.name.endsWith('.ts') || entry.name.endsWith('.tsx')) {
+              // Skip declaration files
+              if (entry.name.endsWith('.d.ts')) {
+                continue;
+              }
+
+              // Skip test files unless explicitly included
+              if (!options.includeTests) {
+                if (entry.name.includes('.test.') || entry.name.includes('.spec.')) {
+                  continue;
+                }
+              }
+
+              files.push(fullPath);
+            }
+          }
+        }
+      } catch (error) {
+        console.error(`[TypeScriptExtractor] Error reading directory ${currentDir}:`, error);
+      }
+    };
+
+    walk(dir);
+    return files;
+  }
+
+  private visitNode(
+    node: ts.Node,
+    sourceFile: ts.SourceFile,
+    checker: ts.TypeChecker,
+    extractedTypes: ExtractedType[],
+    exportedNames: Set<string>,
+    defaultExport: { value?: string },
+    packagePath: string,
+  ) {
+    const modifiers = ts.canHaveModifiers(node) ? ts.getModifiers(node) : undefined;
+    const isExported = modifiers?.some(m => m.kind === ts.SyntaxKind.ExportKeyword) || false;
+    const isDefaultExport = modifiers?.some(m => m.kind === ts.SyntaxKind.DefaultKeyword) || false;
+
+    // Extract JSDoc comments
+    const jsDoc = this.getJSDocComment(node, sourceFile);
+
+    // Get relative file path from package root
+    const getRelativeFileName = (): string => {
+      const relativePath = path.relative(packagePath, sourceFile.fileName);
+      return relativePath.startsWith('.') ? relativePath : `./${relativePath}`;
+    };
+
+    if (ts.isInterfaceDeclaration(node)) {
+      const name = node.name?.text || 'Anonymous';
+      const text = this.getNodeText(node, sourceFile);
+
+      // Only extract exported types
+      if (isExported) {
+        extractedTypes.push({
+          name,
+          kind: 'interface',
+          text,
+          fileName: getRelativeFileName(),
+          isExported,
+          jsDoc,
+        });
+
+        exportedNames.add(name);
+      }
+
+      if (isDefaultExport) {
+        defaultExport.value = name;
+      }
+    } else if (ts.isTypeAliasDeclaration(node)) {
+      const name = node.name?.text || 'Anonymous';
+      const text = this.getNodeText(node, sourceFile);
+
+      if (isExported) {
+        extractedTypes.push({
+          name,
+          kind: 'type',
+          text,
+          fileName: getRelativeFileName(),
+          isExported,
+          jsDoc,
+        });
+
+        exportedNames.add(name);
+      }
+
+      if (isDefaultExport) {
+        defaultExport.value = name;
+      }
+    } else if (ts.isClassDeclaration(node)) {
+      const name = node.name?.text || 'Anonymous';
+      const text = this.getClassSignature(node, sourceFile, checker);
+
+      if (isExported) {
+        extractedTypes.push({
+          name,
+          kind: 'class',
+          text,
+          fileName: getRelativeFileName(),
+          isExported,
+          jsDoc,
+        });
+
+        exportedNames.add(name);
+      }
+
+      if (isDefaultExport) {
+        defaultExport.value = name;
+      }
+    } else if (ts.isEnumDeclaration(node)) {
+      const name = node.name?.text || 'Anonymous';
+      const text = this.getNodeText(node, sourceFile);
+
+      if (isExported) {
+        extractedTypes.push({
+          name,
+          kind: 'enum',
+          text,
+          fileName: getRelativeFileName(),
+          isExported,
+          jsDoc,
+        });
+
+        exportedNames.add(name);
+      }
+
+      if (isDefaultExport) {
+        defaultExport.value = name;
+      }
+    } else if (ts.isFunctionDeclaration(node) && node.name) {
+      const name = node.name.text;
+      const text = this.getFunctionSignature(node, sourceFile, checker);
+
+      if (isExported) {
+        extractedTypes.push({
+          name,
+          kind: 'function',
+          text,
+          fileName: getRelativeFileName(),
+          isExported,
+          jsDoc,
+        });
+
+        exportedNames.add(name);
+      }
+
+      if (isDefaultExport) {
+        defaultExport.value = name;
+      }
+    }
+
+    // Handle export default statements separately
+    if (ts.isExportAssignment(node) && !node.isExportEquals) {
+      // This is an "export default" statement
+      if (ts.isIdentifier(node.expression)) {
+        defaultExport.value = node.expression.text;
+      }
+    }
+
+    // Continue visiting child nodes
+    ts.forEachChild(node, child => {
+      this.visitNode(
+        child,
+        sourceFile,
+        checker,
+        extractedTypes,
+        exportedNames,
+        defaultExport,
+        packagePath,
+      );
+    });
+  }
+
+  private getNodeText(node: ts.Node, sourceFile: ts.SourceFile): string {
+    return node.getText(sourceFile);
+  }
+
+  private getJSDocComment(node: ts.Node, _sourceFile: ts.SourceFile): string | undefined {
+    // Get the full JSDoc comments including the main comment and tags
+    const jsDocComments = ts.getJSDocCommentsAndTags(node);
+    if (jsDocComments.length === 0) return undefined;
+
+    const comments: string[] = [];
+
+    jsDocComments.forEach(comment => {
+      if (ts.isJSDoc(comment)) {
+        // Get the main comment text
+        if (comment.comment) {
+          if (typeof comment.comment === 'string') {
+            comments.push(comment.comment);
+          } else if (Array.isArray(comment.comment)) {
+            comments.push(comment.comment.map(c => c.text).join(''));
+          }
+        }
+
+        // Get text from tags (like @description)
+        comment.tags?.forEach(tag => {
+          if (tag.comment) {
+            if (typeof tag.comment === 'string') {
+              comments.push(tag.comment);
+            } else if (Array.isArray(tag.comment)) {
+              comments.push(tag.comment.map(c => c.text).join(''));
+            }
+          }
+        });
+      }
+    });
+
+    return comments.length > 0 ? comments.join('\n') : undefined;
+  }
+
+  private getClassSignature(
+    node: ts.ClassDeclaration,
+    sourceFile: ts.SourceFile,
+    _checker: ts.TypeChecker,
+  ): string {
+    // For now, return the full class declaration
+    // In the future, we could extract just the public API
+    return this.getNodeText(node, sourceFile);
+  }
+
+  private getFunctionSignature(
+    node: ts.FunctionDeclaration,
+    sourceFile: ts.SourceFile,
+    _checker: ts.TypeChecker,
+  ): string {
+    // Get just the function signature without the body
+    const signature = node.name?.text || 'anonymous';
+    const params = node.parameters.map(p => p.getText(sourceFile)).join(', ');
+    const returnType = node.type ? `: ${node.type.getText(sourceFile)}` : '';
+
+    return `function ${signature}(${params})${returnType}`;
+  }
+}

package/src/modules/index.ts

@@ -0,0 +1,13 @@
+// Export layer modules
+export { FileTypeLayerModule } from './FileTypeLayerModule';
+export type { FileTypeInfo } from './FileTypeLayerModule';
+export { PackageLayerModule } from './PackageLayerModule';
+export { VersionControlLayerFactory } from './VersionControlLayerModule';
+export { DependencyLayerModule } from './DependencyLayerModule';
+export { FrameworkLayerModule } from './FrameworkLayerModule';
+export { FileSystemModule } from './FileSystemModule';
+export type { FileSystemModuleConfig, FileSystemLoadResult } from './FileSystemModule';
+export { TypeExtractionModule } from './TypeExtractionModule';
+export type { TypeExtractionOptions } from './TypeExtractionModule';
+export { TypeScriptExtractor } from './extractors/TypeScriptExtractor';
+export type { TypeScriptExtractionOptions } from './extractors/TypeScriptExtractor';