@parseme/cli 0.0.2

package/dist/cli.js

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+import { join } from 'path';
+import { Command } from 'commander';
+import { ParsemeConfig } from './config.js';
+import { ParsemeGenerator } from './generator.js';
+import { confirmPrompt } from './prompt.js';
+const program = new Command();
+async function promptForMissingConfig(config, cliOptions) {
+    const finalConfig = { ...config };
+    // Only prompt if running interactively (stdin is a TTY) and not in CI
+    if (!process.stdin.isTTY || process.env.CI) {
+        return finalConfig;
+    }
+    // Prompt for README suggestion if not set via CLI or config
+    if (cliOptions.readmeSuggestion === undefined && config.readmeSuggestion === undefined) {
+        const wantReadmeSuggestion = await confirmPrompt('Show README.md section suggestion for AI agents?', true);
+        finalConfig.readmeSuggestion = wantReadmeSuggestion;
+    }
+    return finalConfig;
+}
+program.name('parseme').description('AI Project Context Generator').version('0.1.0');
+// Main command - just run parseme
+program
+    .description('Generate project context using config file')
+    .option('-c, --config <path>', 'Config file path')
+    .option('-o, --output <path>', 'Output file path')
+    .option('-r, --root <path>', 'Root directory to analyze')
+    .option('--context-dir <path>', 'Context directory path (default: parseme-context)')
+    .option('--include <patterns...>', 'Include patterns (glob)')
+    .option('--exclude <patterns...>', 'Exclude patterns (glob)')
+    .option('--no-git', 'Disable git information')
+    .option('--max-depth <number>', 'Maximum directory depth', parseInt)
+    .option('--no-readme-suggestion', 'Disable README.md section suggestion')
+    .action(async (options) => {
+    try {
+        // Convert CLI options to config format
+        const cliOptions = {
+            ...(options.output && { outputPath: options.output }),
+            ...(options.root && { rootDir: options.root }),
+            ...(options.contextDir && { contextDir: options.contextDir }),
+            ...(options.include && { includePatterns: options.include }),
+            ...(options.exclude && { excludePatterns: options.exclude }),
+            ...(options.git === false && { includeGitInfo: false }),
+            ...(options.maxDepth && { maxDepth: options.maxDepth }),
+            ...(options.readmeSuggestion === false && { readmeSuggestion: false }),
+        };
+        const configFromFile = await ParsemeConfig.fromFile(options.config);
+        const interactiveConfig = await promptForMissingConfig(configFromFile.get(), cliOptions);
+        // Merge: CLI options > interactive prompts > config file > defaults
+        const finalConfig = {
+            ...interactiveConfig,
+            ...cliOptions,
+        };
+        const config = new ParsemeConfig(finalConfig);
+        const generator = new ParsemeGenerator(config.get());
+        await generator.generateToFile();
+        console.log('Context generated successfully');
+        console.log('Tip: Add parseme as a git hook to keep context auto-updated! See README for setup instructions.');
+        const shouldShowReadmeSuggestion = finalConfig.readmeSuggestion !== false;
+        if (shouldShowReadmeSuggestion) {
+            console.log('Tip: Add this section to your README.md to help AI agents find the context:');
+            console.log('');
+            console.log('## For AI Assistants');
+            console.log('This project includes AI-optimized documentation:');
+            console.log('- `PARSEME.md` - Main project context and overview');
+            console.log('- `parseme-context/` - Detailed JSON files with code structure, dependencies, and git info');
+            console.log('');
+        }
+    }
+    catch (error) {
+        console.error('Failed to generate context:', error);
+        process.exit(1);
+    }
+});
+program
+    .command('init')
+    .description('Initialize parseme configuration')
+    .option('-f, --force', 'Overwrite existing config')
+    .option('--format <format>', 'Config format: js, ts, or json', 'js')
+    .action(async (options) => {
+    try {
+        // Validate format
+        if (!['js', 'ts', 'json'].includes(options.format)) {
+            console.error('Invalid format. Use js, ts, or json');
+            process.exit(1);
+        }
+        const configPath = join(process.cwd(), `parseme.config.${options.format}`);
+        const config = new ParsemeConfig();
+        // Check if config already exists
+        if (!options.force) {
+            try {
+                const fs = await import('fs/promises');
+                await fs.access(configPath);
+                console.log('Configuration file already exists. Use --force to overwrite.');
+                process.exit(1);
+            }
+            catch {
+                // File doesn't exist, continue
+            }
+        }
+        await config.save(configPath);
+        console.log(`Configuration file created at ${configPath}`);
+        if (options.format === 'ts') {
+            console.log('For TypeScript configs, ensure tsx or ts-node is available to load .ts files');
+        }
+        console.log('Add "parseme": "parseme" to your package.json scripts');
+    }
+    catch (error) {
+        console.error('Failed to create configuration:', error);
+        process.exit(1);
+    }
+});
+// If no command and no args, run main action
+if (process.argv.length <= 2) {
+    // Run the default action
+    (async () => {
+        try {
+            const configFromFile = await ParsemeConfig.fromFile();
+            const interactiveConfig = await promptForMissingConfig(configFromFile.get(), {});
+            const config = new ParsemeConfig(interactiveConfig);
+            const generator = new ParsemeGenerator(config.get());
+            await generator.generateToFile();
+            console.log('Context generated successfully');
+            console.log('Tip: Add parseme as a git hook to keep context auto-updated! See README for setup instructions.');
+            const shouldShowReadmeSuggestion = interactiveConfig.readmeSuggestion !== false;
+            if (shouldShowReadmeSuggestion) {
+                console.log('Tip: Add this section to your README.md to help AI agents find the context:');
+                console.log('');
+                console.log('## For AI Assistants');
+                console.log('This project includes AI-optimized documentation:');
+                console.log('- `PARSEME.md` - Main project context and overview');
+                console.log('- `parseme-context/` - Detailed JSON files with code structure, dependencies, and git info');
+                console.log('');
+            }
+        }
+        catch (error) {
+            console.error('Failed to generate context:', error);
+            console.log('Run "parseme init" to create a configuration file');
+            process.exit(1);
+        }
+    })();
+}
+else {
+    program.parse();
+}

package/dist/config.d.ts

@@ -0,0 +1,44 @@
+import type { GeneratorOptions } from './types.js';
+export interface ParsemeConfigFile extends GeneratorOptions {
+    outputPath?: string;
+    contextDir?: string;
+    rootDir?: string;
+    includePatterns?: string[];
+    excludePatterns?: string[];
+    maxDepth?: number;
+    includeGitInfo?: boolean;
+    readmeSuggestion?: boolean;
+    sections?: {
+        overview?: boolean;
+        architecture?: boolean;
+        routes?: boolean;
+        dependencies?: boolean;
+        git?: boolean;
+        fileStructure?: boolean;
+    };
+    style?: {
+        includeLineNumbers?: boolean;
+        includeFileStats?: boolean;
+        groupByType?: boolean;
+        sortOrder?: 'alphabetical' | 'type' | 'size';
+    };
+    limits?: {
+        maxLinesPerFile?: number;
+        maxCharsPerFile?: number;
+        maxFilesPerContext?: number;
+        truncateStrategy?: 'truncate' | 'split' | 'summarize';
+    };
+}
+export declare class ParsemeConfig {
+    private readonly config;
+    constructor(config?: Partial<ParsemeConfigFile>);
+    static fromFileWithOptions(configPath?: string, cliOptions?: Partial<ParsemeConfigFile>): Promise<ParsemeConfig>;
+    static fromFile(configPath?: string): Promise<ParsemeConfig>;
+    private mergeWithDefaults;
+    get(): ParsemeConfigFile;
+    save(path?: string): Promise<void>;
+    private generateJSConfig;
+    private generateTSConfig;
+    private mergeExcludePatterns;
+    private readGitignorePatterns;
+}

package/dist/config.js

@@ -0,0 +1,203 @@
+import { readFileSync, existsSync } from 'fs';
+import { readFile, writeFile } from 'fs/promises';
+import { join, extname } from 'path';
+export class ParsemeConfig {
+    config;
+    constructor(config = {}) {
+        this.config = this.mergeWithDefaults(config);
+    }
+    static async fromFileWithOptions(configPath, cliOptions = {}) {
+        const configFromFile = await ParsemeConfig.fromFile(configPath);
+        const mergedConfig = {
+            ...configFromFile.get(),
+            ...cliOptions, // CLI options take priority
+        };
+        return new ParsemeConfig(mergedConfig);
+    }
+    static async fromFile(configPath) {
+        const defaultPaths = [
+            'parseme.config.ts',
+            'parseme.config.js',
+            'parseme.config.json',
+            '.parsemerc.ts',
+            '.parsemerc.js',
+            '.parsemerc.json',
+            '.parsemerc',
+        ];
+        const paths = configPath ? [configPath] : defaultPaths;
+        for (const path of paths) {
+            try {
+                const ext = extname(path);
+                if (ext === '.js' || ext === '.ts') {
+                    // Dynamic import for JS/TS config files
+                    const fullPath = path.startsWith('/') ? path : join(process.cwd(), path);
+                    if (ext === '.ts') {
+                        // For TypeScript files, try to import directly first
+                        // This works if the user has transpiled their TS config to JS or is using tsx/ts-node
+                        try {
+                            const module = await import(fullPath);
+                            const config = module.default || module;
+                            return new ParsemeConfig(config);
+                        }
+                        catch {
+                            // If direct import fails, suggest using .js instead
+                            console.warn(`Could not load TypeScript config file: ${path}`);
+                            console.warn(`Consider using a .js config file or ensure tsx/ts-node is available`);
+                        }
+                    }
+                    else {
+                        // JavaScript files
+                        const module = await import(fullPath);
+                        const config = module.default || module;
+                        return new ParsemeConfig(config);
+                    }
+                }
+                else {
+                    // JSON config files
+                    const content = await readFile(path, 'utf-8');
+                    const config = JSON.parse(content);
+                    return new ParsemeConfig(config);
+                }
+            }
+            catch {
+                // Continue to next path
+            }
+        }
+        // Return default config if no file found
+        return new ParsemeConfig();
+    }
+    mergeWithDefaults(config) {
+        const rootDir = config.rootDir || process.cwd();
+        return {
+            // Output
+            outputPath: config.outputPath || 'PARSEME.md',
+            contextDir: config.contextDir || 'parseme-context',
+            // Analysis
+            rootDir,
+            maxDepth: config.maxDepth || 10,
+            excludePatterns: this.mergeExcludePatterns(config.excludePatterns, rootDir),
+            includePatterns: config.includePatterns || [
+                'src/**/*.ts',
+                'src/**/*.js',
+                'src/**/*.tsx',
+                'src/**/*.jsx',
+                'lib/**/*.ts',
+                'lib/**/*.js',
+                'package.json',
+                'tsconfig.json',
+                'README.md',
+            ],
+            // Git
+            includeGitInfo: config.includeGitInfo ?? true,
+            // Sections
+            sections: {
+                overview: true,
+                architecture: true,
+                routes: true,
+                dependencies: true,
+                git: true,
+                fileStructure: true,
+                ...config.sections,
+            },
+            // Style
+            style: {
+                includeLineNumbers: false,
+                includeFileStats: true,
+                groupByType: true,
+                sortOrder: 'type',
+                ...config.style,
+            },
+            // Size limits
+            limits: {
+                maxLinesPerFile: config.limits?.maxLinesPerFile ?? 1000,
+                maxCharsPerFile: config.limits?.maxCharsPerFile ?? 50000, // ~15k tokens
+                maxFilesPerContext: config.limits?.maxFilesPerContext ?? 20,
+                truncateStrategy: config.limits?.truncateStrategy ?? 'truncate',
+            },
+        };
+    }
+    get() {
+        return { ...this.config };
+    }
+    async save(path = 'parseme.config.js') {
+        const ext = extname(path);
+        if (ext === '.js') {
+            // Generate JavaScript config file
+            const configContent = this.generateJSConfig();
+            await writeFile(path, configContent);
+        }
+        else if (ext === '.ts') {
+            // Generate TypeScript config file
+            const configContent = this.generateTSConfig();
+            await writeFile(path, configContent);
+        }
+        else {
+            // Generate JSON config file
+            await writeFile(path, JSON.stringify(this.config, null, 2));
+        }
+    }
+    generateJSConfig() {
+        return `/** @type {import('parseme').ParsemeConfigFile} */
+export default ${JSON.stringify(this.config, null, 2)};
+`;
+    }
+    generateTSConfig() {
+        return `import type { ParsemeConfigFile } from 'parseme';
+
+const config: ParsemeConfigFile = ${JSON.stringify(this.config, null, 2)};
+
+export default config;
+`;
+    }
+    mergeExcludePatterns(configPatterns, rootDir) {
+        const defaultPatterns = [
+            'node_modules/**',
+            'dist/**',
+            'build/**',
+            'coverage/**',
+            '.git/**',
+            '**/*.log',
+            '**/*.tmp',
+            '**/.DS_Store',
+            '**/.*',
+        ];
+        // Priority: Config patterns > .gitignore patterns > Default patterns
+        if (configPatterns) {
+            return configPatterns;
+        }
+        // Try to read .gitignore patterns
+        const gitignorePatterns = this.readGitignorePatterns(rootDir);
+        if (gitignorePatterns.length > 0) {
+            // Merge gitignore patterns with critical defaults
+            const criticalDefaults = ['node_modules/**', '.git/**'];
+            return [...new Set([...criticalDefaults, ...gitignorePatterns])];
+        }
+        return defaultPatterns;
+    }
+    readGitignorePatterns(rootDir) {
+        try {
+            const gitignorePath = join(rootDir, '.gitignore');
+            if (!existsSync(gitignorePath)) {
+                return [];
+            }
+            const gitignoreContent = readFileSync(gitignorePath, 'utf-8');
+            return gitignoreContent
+                .split('\n')
+                .map((line) => line.trim())
+                .filter((line) => line && !line.startsWith('#'))
+                .map((pattern) => {
+                // Convert gitignore patterns to glob patterns
+                if (pattern.endsWith('/')) {
+                    return pattern + '**';
+                }
+                if (!pattern.includes('/') && !pattern.includes('*')) {
+                    return '**/' + pattern;
+                }
+                return pattern;
+            });
+        }
+        catch {
+            return [];
+        }
+    }
+}

package/dist/generator.d.ts

@@ -0,0 +1,15 @@
+import { type ParsemeConfigFile } from './config.js';
+import type { ContextOutput, GeneratorOptions } from './types.js';
+export declare class ParsemeGenerator {
+    private readonly config;
+    private readonly projectAnalyzer;
+    private readonly astAnalyzer;
+    private readonly frameworkDetector;
+    private readonly gitAnalyzer;
+    private readonly contextBuilder;
+    constructor(options?: GeneratorOptions);
+    static fromConfig(configPath?: string): Promise<ParsemeGenerator>;
+    static fromConfigWithOptions(configPath?: string, cliOptions?: Partial<ParsemeConfigFile>): Promise<ParsemeGenerator>;
+    generate(outputPath?: string): Promise<ContextOutput>;
+    generateToFile(outputPath?: string, contextDir?: string): Promise<void>;
+}

package/dist/generator.js

@@ -0,0 +1,88 @@
+import { mkdir, writeFile } from 'fs/promises';
+import { join } from 'path';
+import { ASTAnalyzer } from './analyzers/ast-analyzer.js';
+import { FrameworkDetector } from './analyzers/framework-detector.js';
+import { GitAnalyzer } from './analyzers/git-analyzer.js';
+import { ProjectAnalyzer } from './analyzers/project-analyzer.js';
+import { ContextBuilder } from './builders/context-builder.js';
+import { ParsemeConfig } from './config.js';
+export class ParsemeGenerator {
+    config;
+    projectAnalyzer;
+    astAnalyzer;
+    frameworkDetector;
+    gitAnalyzer;
+    contextBuilder;
+    constructor(options = {}) {
+        this.config = new ParsemeConfig(options);
+        this.projectAnalyzer = new ProjectAnalyzer(this.config);
+        this.astAnalyzer = new ASTAnalyzer(this.config);
+        this.frameworkDetector = new FrameworkDetector(this.config);
+        this.gitAnalyzer = new GitAnalyzer(this.config);
+        this.contextBuilder = new ContextBuilder(this.config);
+    }
+    static async fromConfig(configPath) {
+        const config = await ParsemeConfig.fromFile(configPath);
+        return new ParsemeGenerator(config.get());
+    }
+    static async fromConfigWithOptions(configPath, cliOptions = {}) {
+        const config = await ParsemeConfig.fromFileWithOptions(configPath, cliOptions);
+        return new ParsemeGenerator(config.get());
+    }
+    async generate(outputPath) {
+        const configData = this.config.get();
+        // Step 1: Analyze the project structure and metadata
+        const projectInfo = await this.projectAnalyzer.analyze(configData.rootDir);
+        // Step 2: Detect framework and analyze specific patterns
+        projectInfo.framework = await this.frameworkDetector.detect(projectInfo);
+        // Step 3: Analyze all relevant files with AST
+        const fileAnalyses = await this.astAnalyzer.analyzeProject(configData.rootDir);
+        // Step 4: Get git information if enabled
+        const gitInfo = configData.includeGitInfo
+            ? await this.gitAnalyzer.analyze(configData.rootDir)
+            : undefined;
+        // Calculate final output path for link generation
+        const finalOutputPath = outputPath || configData.outputPath || join(configData.rootDir, 'PARSEME.md');
+        // Step 5: Build the context output
+        return this.contextBuilder.build({
+            projectInfo,
+            fileAnalyses,
+            gitInfo,
+            options: configData,
+            contextDir: configData.contextDir,
+            outputPath: finalOutputPath,
+        });
+    }
+    async generateToFile(outputPath, contextDir) {
+        // Use outputPath from config if not specified
+        const configData = this.config.get();
+        let finalOutputPath;
+        if (outputPath) {
+            finalOutputPath = outputPath;
+        }
+        else if (configData.outputPath) {
+            // If outputPath is relative, resolve it relative to rootDir
+            finalOutputPath = configData.outputPath.startsWith('/')
+                ? configData.outputPath
+                : join(configData.rootDir, configData.outputPath);
+        }
+        else {
+            finalOutputPath = join(configData.rootDir, 'PARSEME.md');
+        }
+        const context = await this.generate(finalOutputPath);
+        // Use contextDir from config if not specified
+        const finalContextDir = contextDir || configData.contextDir || 'parseme-context';
+        // If contextDir is relative, make it relative to the output file's directory
+        const baseDir = join(finalOutputPath, '..');
+        const parsemeDir = finalContextDir.startsWith('/')
+            ? finalContextDir // Absolute path
+            : join(baseDir, finalContextDir); // Relative path
+        await mkdir(parsemeDir, { recursive: true });
+        await writeFile(finalOutputPath, context.parseme);
+        if (context.context) {
+            for (const [filename, content] of Object.entries(context.context)) {
+                await writeFile(join(parsemeDir, `${filename}.json`), content);
+            }
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { ParsemeGenerator } from './generator.js';
+export { ParsemeConfig } from './config.js';
+export type { GeneratorOptions, ContextOutput, ProjectInfo, FrameworkInfo, RouteInfo, FileAnalysis, GitInfo, } from './types.js';
+export type { ParsemeConfigFile } from './config.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+// Main exports for the parseme package
+export { ParsemeGenerator } from './generator.js';
+export { ParsemeConfig } from './config.js';

package/dist/prompt.d.ts

@@ -0,0 +1,8 @@
+interface PromptOptions {
+    message: string;
+    defaultValue?: string;
+    choices?: string[];
+}
+export declare function prompt(options: PromptOptions): Promise<string>;
+export declare function confirmPrompt(message: string, defaultValue?: boolean): Promise<boolean>;
+export {};

package/dist/prompt.js

@@ -0,0 +1,42 @@
+import { createInterface } from 'readline';
+export async function prompt(options) {
+    const rl = createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    return new Promise((resolve) => {
+        const { message, defaultValue, choices } = options;
+        let promptMessage = message;
+        if (choices) {
+            promptMessage += ` (${choices.join('/')})`;
+        }
+        if (defaultValue) {
+            promptMessage += ` [${defaultValue}]`;
+        }
+        promptMessage += ': ';
+        rl.question(promptMessage, (answer) => {
+            rl.close();
+            const trimmed = answer.trim();
+            if (!trimmed && defaultValue) {
+                resolve(defaultValue);
+            }
+            else if (choices && trimmed) {
+                const normalized = trimmed.toLowerCase();
+                const match = choices.find((choice) => choice.toLowerCase().startsWith(normalized));
+                resolve(match || trimmed);
+            }
+            else {
+                resolve(trimmed);
+            }
+        });
+    });
+}
+export async function confirmPrompt(message, defaultValue = true) {
+    const answer = await prompt({
+        message,
+        defaultValue: defaultValue ? 'y' : 'n',
+        choices: ['y', 'n', 'yes', 'no'],
+    });
+    const normalized = answer.toLowerCase();
+    return normalized === 'y' || normalized === 'yes';
+}

package/dist/types.d.ts

@@ -0,0 +1,82 @@
+import type { ServiceInfo, ModelInfo, ConfigInfo, MiddlewareInfo, UtilityInfo } from './analyzers/pattern-detector.js';
+export type { ServiceInfo, ModelInfo, ConfigInfo, MiddlewareInfo, UtilityInfo };
+export interface GeneratorOptions {
+    rootDir?: string;
+    includeGitInfo?: boolean;
+    maxDepth?: number;
+    excludePatterns?: string[];
+    includePatterns?: string[];
+}
+export interface ProjectInfo {
+    name: string;
+    version?: string;
+    description?: string;
+    type: 'typescript' | 'javascript' | 'mixed';
+    category: ProjectCategory;
+    packageManager: 'npm' | 'yarn' | 'pnpm' | 'bun';
+    framework?: FrameworkInfo;
+    buildTool?: BuildToolInfo;
+    dependencies: Record<string, string>;
+    devDependencies: Record<string, string>;
+    scripts?: Record<string, string>;
+    entryPoints?: string[];
+    outputTargets?: string[];
+}
+export type ProjectCategory = 'backend-api' | 'frontend-web' | 'frontend-mobile' | 'npm-package' | 'monorepo' | 'cli-tool' | 'desktop-app' | 'fullstack' | 'unknown';
+export interface BuildToolInfo {
+    name: string;
+    version?: string;
+    configFiles: string[];
+    features: string[];
+}
+export interface FrameworkInfo {
+    name: string;
+    version?: string;
+    features: string[];
+    routes?: RouteInfo[];
+    components?: ComponentInfo[];
+}
+export interface RouteInfo {
+    method: string;
+    path: string;
+    handler: string;
+    middleware?: string[];
+    file: string;
+    line: number;
+}
+export interface ComponentInfo {
+    name: string;
+    file: string;
+    line: number;
+}
+export interface FileAnalysis {
+    path: string;
+    type: 'route' | 'middleware' | 'model' | 'service' | 'utility' | 'config' | 'test' | 'component';
+    framework?: string;
+    exports: string[];
+    imports: string[];
+    functions: string[];
+    classes: string[];
+    routes?: RouteInfo[];
+    components?: ComponentInfo[];
+    services?: ServiceInfo[];
+    models?: ModelInfo[];
+    configs?: ConfigInfo[];
+    middleware?: MiddlewareInfo[];
+    utilities?: UtilityInfo[];
+}
+export interface ContextOutput {
+    parseme: string;
+    context?: {
+        structure: string;
+        routes: string;
+        dependencies: string;
+        [key: string]: string;
+    };
+}
+export interface GitInfo {
+    branch: string;
+    lastCommit: string;
+    changedFiles: string[];
+    status: 'clean' | 'dirty';
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+// Core types for the parseme package
+export {};