@aiready/core 0.7.13 → 0.8.0

package/dist/index.d.mts

@@ -102,13 +102,173 @@ interface Report {
     };
 }
 
+/**
+ * Language-agnostic AST and parser interfaces for multi-language support
+ *
+ * This module provides abstractions for parsing different programming languages
+ * while maintaining a consistent interface for analysis tools.
+ */
+/**
+ * Supported programming languages
+ */
+declare enum Language {
+    TypeScript = "typescript",
+    JavaScript = "javascript",
+    Python = "python",
+    Java = "java",
+    Go = "go",
+    Rust = "rust",
+    CSharp = "csharp"
+}
+/**
+ * File extensions mapped to languages
+ */
+declare const LANGUAGE_EXTENSIONS: Record<string, Language>;
+/**
+ * Location information in source code
+ */
+interface SourceLocation {
+    line: number;
+    column: number;
+}
+interface SourceRange {
+    start: SourceLocation;
+    end: SourceLocation;
+}
+/**
+ * Common AST node type (language-agnostic)
+ */
+interface CommonASTNode {
+    type: string;
+    loc?: SourceRange;
+    raw?: any;
+}
+/**
+ * Export information (function, class, variable, etc.)
+ */
+interface ExportInfo {
+    name: string;
+    type: 'function' | 'class' | 'const' | 'type' | 'interface' | 'default' | 'variable';
+    loc?: SourceRange;
+    /** Imports used within this export */
+    imports?: string[];
+    /** Dependencies on other exports in same file */
+    dependencies?: string[];
+    /** TypeScript types referenced */
+    typeReferences?: string[];
+    /** For methods: parent class name */
+    parentClass?: string;
+    /** For functions/methods: parameters */
+    parameters?: string[];
+    /** Visibility (public, private, protected) */
+    visibility?: 'public' | 'private' | 'protected';
+}
+/**
+ * Import information
+ */
+interface ImportInfo {
+    /** Module being imported from */
+    source: string;
+    /** What's being imported */
+    specifiers: string[];
+    /** Is this a type-only import (TypeScript) */
+    isTypeOnly?: boolean;
+    /** Location in source */
+    loc?: SourceRange;
+}
+/**
+ * Parse result containing exports and imports
+ */
+interface ParseResult {
+    exports: ExportInfo[];
+    imports: ImportInfo[];
+    /** Language of the parsed file */
+    language: Language;
+    /** Any parse warnings (non-fatal) */
+    warnings?: string[];
+}
+/**
+ * Naming convention rules per language
+ */
+interface NamingConvention {
+    /** Allowed variable naming patterns */
+    variablePattern: RegExp;
+    /** Allowed function naming patterns */
+    functionPattern: RegExp;
+    /** Allowed class naming patterns */
+    classPattern: RegExp;
+    /** Allowed constant naming patterns */
+    constantPattern: RegExp;
+    /** Language-specific exceptions (e.g., __init__ in Python) */
+    exceptions?: string[];
+}
+/**
+ * Language-specific configuration
+ */
+interface LanguageConfig {
+    language: Language;
+    /** File extensions for this language */
+    extensions: string[];
+    /** Naming conventions */
+    namingConventions: NamingConvention;
+    /** Common abbreviations allowed */
+    allowedAbbreviations?: string[];
+    /** Language-specific keywords to ignore */
+    keywords?: string[];
+}
+/**
+ * Abstract interface for language parsers
+ * Each language implementation should implement this interface
+ */
+interface LanguageParser {
+    /** Language this parser handles */
+    readonly language: Language;
+    /** File extensions this parser supports */
+    readonly extensions: string[];
+    /**
+     * Parse source code and extract structure
+     * @param code - Source code to parse
+     * @param filePath - Path to the file (for context)
+     * @returns Parse result with exports and imports
+     * @throws ParseError if code has syntax errors
+     */
+    parse(code: string, filePath: string): ParseResult;
+    /**
+     * Get naming conventions for this language
+     */
+    getNamingConventions(): NamingConvention;
+    /**
+     * Check if this parser can handle a file
+     * @param filePath - File path to check
+     */
+    canHandle(filePath: string): boolean;
+}
+/**
+ * Parser error with location information
+ */
+declare class ParseError extends Error {
+    readonly filePath: string;
+    readonly loc?: SourceLocation | undefined;
+    constructor(message: string, filePath: string, loc?: SourceLocation | undefined);
+}
+/**
+ * Statistics about parsed code
+ */
+interface ParseStatistics {
+    language: Language;
+    filesAnalyzed: number;
+    totalExports: number;
+    totalImports: number;
+    parseErrors: number;
+    warnings: number;
+}
+
 declare const DEFAULT_EXCLUDE: string[];
 /**
  * Scan files in a directory using glob patterns
  *
- * Note: This scanner includes multiple language file types by default (.ts, .tsx, .js, .jsx, .py, .java)
- * to support potential multi-language analysis in the future. Individual tools (like @aiready/consistency)
- * should filter to their supported languages before processing.
+ * Note: This scanner supports multiple languages (.ts, .tsx, .js, .jsx, .py, .java, etc.)
+ * Individual tools can filter to their supported languages if needed.
  *
  * @param options - Scan configuration
  * @returns Array of absolute file paths matching the patterns
@@ -324,4 +484,132 @@ declare function formatScore(result: ScoringResult): string;
  */
 declare function formatToolScore(output: ToolScoringOutput): string;
 
-export { type AIReadyConfig, type ASTNode, type AnalysisResult, type CLIOptions, DEFAULT_EXCLUDE, DEFAULT_TOOL_WEIGHTS, type ExportWithImports, type FileImport, type Issue, type IssueType, type Location, type Metrics, type Report, type ScanOptions, type ScoringConfig, type ScoringResult, TOOL_NAME_MAP, type ToolScoringOutput, calculateImportSimilarity, calculateOverallScore, estimateTokens, extractFunctions, extractImports, formatScore, formatToolScore, getElapsedTime, getFileExtension, getRating, getRatingDisplay, getToolWeight, handleCLIError, handleJSONOutput, isSourceFile, loadConfig, loadMergedConfig, mergeConfigWithDefaults, normalizeToolName, parseCode, parseFileExports, parseWeightString, readFileContent, resolveOutputPath, scanFiles };
+/**
+ * Parser Factory - Manages language-specific parsers
+ *
+ * This factory provides a centralized way to access the appropriate parser
+ * for a given file based on its extension.
+ */
+
+/**
+ * Factory for creating and managing language parsers
+ */
+declare class ParserFactory {
+    private static instance;
+    private parsers;
+    private extensionMap;
+    private constructor();
+    /**
+     * Get singleton instance
+     */
+    static getInstance(): ParserFactory;
+    /**
+     * Register a language parser
+     */
+    registerParser(parser: LanguageParser): void;
+    /**
+     * Get parser for a specific language
+     */
+    getParserForLanguage(language: Language): LanguageParser | null;
+    /**
+     * Get parser for a file based on its extension
+     */
+    getParserForFile(filePath: string): LanguageParser | null;
+    /**
+     * Check if a file is supported
+     */
+    isSupported(filePath: string): boolean;
+    /**
+     * Get all registered languages
+     */
+    getSupportedLanguages(): Language[];
+    /**
+     * Get all supported file extensions
+     */
+    getSupportedExtensions(): string[];
+    /**
+     * Get language for a file
+     */
+    getLanguageForFile(filePath: string): Language | null;
+    /**
+     * Extract file extension (with dot)
+     */
+    private getFileExtension;
+    /**
+     * Reset factory (useful for testing)
+     */
+    static reset(): void;
+}
+/**
+ * Convenience function to get parser for a file
+ */
+declare function getParser(filePath: string): LanguageParser | null;
+/**
+ * Convenience function to check if file is supported
+ */
+declare function isFileSupported(filePath: string): boolean;
+/**
+ * Get all supported languages
+ */
+declare function getSupportedLanguages(): Language[];
+
+/**
+ * TypeScript/JavaScript Parser
+ *
+ * Parses TypeScript and JavaScript files using @typescript-eslint/typescript-estree
+ */
+
+declare class TypeScriptParser implements LanguageParser {
+    readonly language = Language.TypeScript;
+    readonly extensions: string[];
+    parse(code: string, filePath: string): ParseResult;
+    getNamingConventions(): NamingConvention;
+    canHandle(filePath: string): boolean;
+    private extractImports;
+    private extractExports;
+    private extractFromDeclaration;
+}
+
+/**
+ * Python Parser using tree-sitter
+ *
+ * Parses Python files using tree-sitter-python for accurate AST parsing
+ */
+
+/**
+ * Python Parser implementation
+ *
+ * Note: This implementation will use tree-sitter-python for parsing.
+ * For now, it provides a skeleton that can be filled in once web-tree-sitter
+ * is properly configured.
+ */
+declare class PythonParser implements LanguageParser {
+    readonly language = Language.Python;
+    readonly extensions: string[];
+    private parser;
+    private initialized;
+    /**
+     * Initialize the tree-sitter parser
+     * This is async because tree-sitter WASM needs to be loaded
+     */
+    initialize(): Promise<void>;
+    parse(code: string, filePath: string): ParseResult;
+    getNamingConventions(): NamingConvention;
+    canHandle(filePath: string): boolean;
+    /**
+     * Regex-based import extraction (temporary implementation)
+     */
+    private extractImportsRegex;
+    /**
+     * Regex-based export extraction (temporary implementation)
+     *
+     * Python doesn't have explicit exports like JavaScript.
+     * We extract:
+     * - Functions defined at module level (def)
+     * - Classes defined at module level (class)
+     * - Variables in __all__ list
+     */
+    private extractExportsRegex;
+}
+
+export { type AIReadyConfig, type ASTNode, type AnalysisResult, type CLIOptions, type CommonASTNode, DEFAULT_EXCLUDE, DEFAULT_TOOL_WEIGHTS, type ExportInfo, type ExportWithImports, type FileImport, type ImportInfo, type Issue, type IssueType, LANGUAGE_EXTENSIONS, Language, type LanguageConfig, type LanguageParser, type Location, type Metrics, type NamingConvention, ParseError, type ParseResult, type ParseStatistics, ParserFactory, PythonParser, type Report, type ScanOptions, type ScoringConfig, type ScoringResult, type SourceLocation, type SourceRange, TOOL_NAME_MAP, type ToolScoringOutput, TypeScriptParser, calculateImportSimilarity, calculateOverallScore, estimateTokens, extractFunctions, extractImports, formatScore, formatToolScore, getElapsedTime, getFileExtension, getParser, getRating, getRatingDisplay, getSupportedLanguages, getToolWeight, handleCLIError, handleJSONOutput, isFileSupported, isSourceFile, loadConfig, loadMergedConfig, mergeConfigWithDefaults, normalizeToolName, parseCode, parseFileExports, parseWeightString, readFileContent, resolveOutputPath, scanFiles };

package/dist/index.d.ts

@@ -102,13 +102,173 @@ interface Report {
     };
 }
 
+/**
+ * Language-agnostic AST and parser interfaces for multi-language support
+ *
+ * This module provides abstractions for parsing different programming languages
+ * while maintaining a consistent interface for analysis tools.
+ */
+/**
+ * Supported programming languages
+ */
+declare enum Language {
+    TypeScript = "typescript",
+    JavaScript = "javascript",
+    Python = "python",
+    Java = "java",
+    Go = "go",
+    Rust = "rust",
+    CSharp = "csharp"
+}
+/**
+ * File extensions mapped to languages
+ */
+declare const LANGUAGE_EXTENSIONS: Record<string, Language>;
+/**
+ * Location information in source code
+ */
+interface SourceLocation {
+    line: number;
+    column: number;
+}
+interface SourceRange {
+    start: SourceLocation;
+    end: SourceLocation;
+}
+/**
+ * Common AST node type (language-agnostic)
+ */
+interface CommonASTNode {
+    type: string;
+    loc?: SourceRange;
+    raw?: any;
+}
+/**
+ * Export information (function, class, variable, etc.)
+ */
+interface ExportInfo {
+    name: string;
+    type: 'function' | 'class' | 'const' | 'type' | 'interface' | 'default' | 'variable';
+    loc?: SourceRange;
+    /** Imports used within this export */
+    imports?: string[];
+    /** Dependencies on other exports in same file */
+    dependencies?: string[];
+    /** TypeScript types referenced */
+    typeReferences?: string[];
+    /** For methods: parent class name */
+    parentClass?: string;
+    /** For functions/methods: parameters */
+    parameters?: string[];
+    /** Visibility (public, private, protected) */
+    visibility?: 'public' | 'private' | 'protected';
+}
+/**
+ * Import information
+ */
+interface ImportInfo {
+    /** Module being imported from */
+    source: string;
+    /** What's being imported */
+    specifiers: string[];
+    /** Is this a type-only import (TypeScript) */
+    isTypeOnly?: boolean;
+    /** Location in source */
+    loc?: SourceRange;
+}
+/**
+ * Parse result containing exports and imports
+ */
+interface ParseResult {
+    exports: ExportInfo[];
+    imports: ImportInfo[];
+    /** Language of the parsed file */
+    language: Language;
+    /** Any parse warnings (non-fatal) */
+    warnings?: string[];
+}
+/**
+ * Naming convention rules per language
+ */
+interface NamingConvention {
+    /** Allowed variable naming patterns */
+    variablePattern: RegExp;
+    /** Allowed function naming patterns */
+    functionPattern: RegExp;
+    /** Allowed class naming patterns */
+    classPattern: RegExp;
+    /** Allowed constant naming patterns */
+    constantPattern: RegExp;
+    /** Language-specific exceptions (e.g., __init__ in Python) */
+    exceptions?: string[];
+}
+/**
+ * Language-specific configuration
+ */
+interface LanguageConfig {
+    language: Language;
+    /** File extensions for this language */
+    extensions: string[];
+    /** Naming conventions */
+    namingConventions: NamingConvention;
+    /** Common abbreviations allowed */
+    allowedAbbreviations?: string[];
+    /** Language-specific keywords to ignore */
+    keywords?: string[];
+}
+/**
+ * Abstract interface for language parsers
+ * Each language implementation should implement this interface
+ */
+interface LanguageParser {
+    /** Language this parser handles */
+    readonly language: Language;
+    /** File extensions this parser supports */
+    readonly extensions: string[];
+    /**
+     * Parse source code and extract structure
+     * @param code - Source code to parse
+     * @param filePath - Path to the file (for context)
+     * @returns Parse result with exports and imports
+     * @throws ParseError if code has syntax errors
+     */
+    parse(code: string, filePath: string): ParseResult;
+    /**
+     * Get naming conventions for this language
+     */
+    getNamingConventions(): NamingConvention;
+    /**
+     * Check if this parser can handle a file
+     * @param filePath - File path to check
+     */
+    canHandle(filePath: string): boolean;
+}
+/**
+ * Parser error with location information
+ */
+declare class ParseError extends Error {
+    readonly filePath: string;
+    readonly loc?: SourceLocation | undefined;
+    constructor(message: string, filePath: string, loc?: SourceLocation | undefined);
+}
+/**
+ * Statistics about parsed code
+ */
+interface ParseStatistics {
+    language: Language;
+    filesAnalyzed: number;
+    totalExports: number;
+    totalImports: number;
+    parseErrors: number;
+    warnings: number;
+}
+
 declare const DEFAULT_EXCLUDE: string[];
 /**
  * Scan files in a directory using glob patterns
  *
- * Note: This scanner includes multiple language file types by default (.ts, .tsx, .js, .jsx, .py, .java)
- * to support potential multi-language analysis in the future. Individual tools (like @aiready/consistency)
- * should filter to their supported languages before processing.
+ * Note: This scanner supports multiple languages (.ts, .tsx, .js, .jsx, .py, .java, etc.)
+ * Individual tools can filter to their supported languages if needed.
  *
  * @param options - Scan configuration
  * @returns Array of absolute file paths matching the patterns
@@ -324,4 +484,132 @@ declare function formatScore(result: ScoringResult): string;
  */
 declare function formatToolScore(output: ToolScoringOutput): string;
 
-export { type AIReadyConfig, type ASTNode, type AnalysisResult, type CLIOptions, DEFAULT_EXCLUDE, DEFAULT_TOOL_WEIGHTS, type ExportWithImports, type FileImport, type Issue, type IssueType, type Location, type Metrics, type Report, type ScanOptions, type ScoringConfig, type ScoringResult, TOOL_NAME_MAP, type ToolScoringOutput, calculateImportSimilarity, calculateOverallScore, estimateTokens, extractFunctions, extractImports, formatScore, formatToolScore, getElapsedTime, getFileExtension, getRating, getRatingDisplay, getToolWeight, handleCLIError, handleJSONOutput, isSourceFile, loadConfig, loadMergedConfig, mergeConfigWithDefaults, normalizeToolName, parseCode, parseFileExports, parseWeightString, readFileContent, resolveOutputPath, scanFiles };
+/**
+ * Parser Factory - Manages language-specific parsers
+ *
+ * This factory provides a centralized way to access the appropriate parser
+ * for a given file based on its extension.
+ */
+
+/**
+ * Factory for creating and managing language parsers
+ */
+declare class ParserFactory {
+    private static instance;
+    private parsers;
+    private extensionMap;
+    private constructor();
+    /**
+     * Get singleton instance
+     */
+    static getInstance(): ParserFactory;
+    /**
+     * Register a language parser
+     */
+    registerParser(parser: LanguageParser): void;
+    /**
+     * Get parser for a specific language
+     */
+    getParserForLanguage(language: Language): LanguageParser | null;
+    /**
+     * Get parser for a file based on its extension
+     */
+    getParserForFile(filePath: string): LanguageParser | null;
+    /**
+     * Check if a file is supported
+     */
+    isSupported(filePath: string): boolean;
+    /**
+     * Get all registered languages
+     */
+    getSupportedLanguages(): Language[];
+    /**
+     * Get all supported file extensions
+     */
+    getSupportedExtensions(): string[];
+    /**
+     * Get language for a file
+     */
+    getLanguageForFile(filePath: string): Language | null;
+    /**
+     * Extract file extension (with dot)
+     */
+    private getFileExtension;
+    /**
+     * Reset factory (useful for testing)
+     */
+    static reset(): void;
+}
+/**
+ * Convenience function to get parser for a file
+ */
+declare function getParser(filePath: string): LanguageParser | null;
+/**
+ * Convenience function to check if file is supported
+ */
+declare function isFileSupported(filePath: string): boolean;
+/**
+ * Get all supported languages
+ */
+declare function getSupportedLanguages(): Language[];
+
+/**
+ * TypeScript/JavaScript Parser
+ *
+ * Parses TypeScript and JavaScript files using @typescript-eslint/typescript-estree
+ */
+
+declare class TypeScriptParser implements LanguageParser {
+    readonly language = Language.TypeScript;
+    readonly extensions: string[];
+    parse(code: string, filePath: string): ParseResult;
+    getNamingConventions(): NamingConvention;
+    canHandle(filePath: string): boolean;
+    private extractImports;
+    private extractExports;
+    private extractFromDeclaration;
+}
+
+/**
+ * Python Parser using tree-sitter
+ *
+ * Parses Python files using tree-sitter-python for accurate AST parsing
+ */
+
+/**
+ * Python Parser implementation
+ *
+ * Note: This implementation will use tree-sitter-python for parsing.
+ * For now, it provides a skeleton that can be filled in once web-tree-sitter
+ * is properly configured.
+ */
+declare class PythonParser implements LanguageParser {
+    readonly language = Language.Python;
+    readonly extensions: string[];
+    private parser;
+    private initialized;
+    /**
+     * Initialize the tree-sitter parser
+     * This is async because tree-sitter WASM needs to be loaded
+     */
+    initialize(): Promise<void>;
+    parse(code: string, filePath: string): ParseResult;
+    getNamingConventions(): NamingConvention;
+    canHandle(filePath: string): boolean;
+    /**
+     * Regex-based import extraction (temporary implementation)
+     */
+    private extractImportsRegex;
+    /**
+     * Regex-based export extraction (temporary implementation)
+     *
+     * Python doesn't have explicit exports like JavaScript.
+     * We extract:
+     * - Functions defined at module level (def)
+     * - Classes defined at module level (class)
+     * - Variables in __all__ list
+     */
+    private extractExportsRegex;
+}
+
+export { type AIReadyConfig, type ASTNode, type AnalysisResult, type CLIOptions, type CommonASTNode, DEFAULT_EXCLUDE, DEFAULT_TOOL_WEIGHTS, type ExportInfo, type ExportWithImports, type FileImport, type ImportInfo, type Issue, type IssueType, LANGUAGE_EXTENSIONS, Language, type LanguageConfig, type LanguageParser, type Location, type Metrics, type NamingConvention, ParseError, type ParseResult, type ParseStatistics, ParserFactory, PythonParser, type Report, type ScanOptions, type ScoringConfig, type ScoringResult, type SourceLocation, type SourceRange, TOOL_NAME_MAP, type ToolScoringOutput, TypeScriptParser, calculateImportSimilarity, calculateOverallScore, estimateTokens, extractFunctions, extractImports, formatScore, formatToolScore, getElapsedTime, getFileExtension, getParser, getRating, getRatingDisplay, getSupportedLanguages, getToolWeight, handleCLIError, handleJSONOutput, isFileSupported, isSourceFile, loadConfig, loadMergedConfig, mergeConfigWithDefaults, normalizeToolName, parseCode, parseFileExports, parseWeightString, readFileContent, resolveOutputPath, scanFiles };