@parseme/cli 0.0.4 → 0.0.6

package/README.md

@@ -46,7 +46,7 @@ PARSEME uses AST analysis to identify:
 ## **Language Support**
 
 - **TypeScript** - Full support including advanced types, decorators, interfaces
-- **JavaScript (ES6+)** - Modern JavaScript with all ES features
+- **JavaScript (ES6+)** - Modern JavaScript with ES features
 - **JSX/TSX** - React and other JSX-based frameworks
 - **Mixed codebases** - Projects with both JS and TS files
 
@@ -59,9 +59,6 @@ PARSEME aims to automatically analyse any JavaScript or TypeScript project like:
 - **NestJS** - Controllers, services, decorators, dependency injection
 - **Express.js** - Routes, middleware, error handlers
 - **Fastify** - Route registration, plugins, hooks
-- **Koa.js** - Context-based middleware, routing
-- **Hapi.js** - Route configuration, server plugins
-- **Custom frameworks** - Any HTTP endpoint patterns
 
 ### **Frontend Applications**
 
@@ -70,28 +67,26 @@ PARSEME aims to automatically analyse any JavaScript or TypeScript project like:
 - **Angular** - Components, services, decorators, modules
 - **Svelte** - Components, stores, reactive patterns
 - **Lit** - Web components, custom elements
-- **Vanilla JS/TS** - Any component or module patterns
+- **Vanilla JS/TS** - Functions, classes, modules, event handlers
 
-### **NPM Packages & Libraries**
+### **Fullstack Frameworks**
 
-- **TypeScript libraries** - Interfaces, types, utility functions
-- **JavaScript utilities** - Helper functions, class libraries
-- **Node.js modules** - CommonJS and ES modules
-- **Monorepo packages** - Lerna, Nx, Rush, Turborepo
+- **Next.js** - Pages, API routes, middleware, components
+- **Nuxt.js** - Pages, server routes, composables, components
 
-### **Development Tools**
+### **Packages & Libraries**
 
-- **CLI applications** - Command-line tools and scripts
-- **Build tools** - Webpack plugins, Vite configurations
-- **Desktop applications** - Electron, Tauri apps
-- **Testing utilities** - Jest plugins, test helpers
+- **TypeScript utilities** - Types, interfaces, enums, generic helpers
+- **JavaScript helpers** - Functions, classes, utilities, data manipulation
+- **Node.js modules** - Exports, imports, CommonJS/ESM patterns
+- **Monorepo packages** - Shared utilities, cross-package dependencies
 
-### **Fullstack Frameworks**
+### **Development Tools**
 
-- **Next.js** - Pages, API routes, middleware, components
-- **Nuxt.js** - Vue-based fullstack applications
-- **SvelteKit** - Svelte-based fullstack applications
-- **Remix** - React-based fullstack applications
+- **CLI tools** - Commands, options, argument parsing
+- **Build plugins** - Plugin functions, configuration handlers
+- **Desktop apps** - Main processes, renderers, IPC handlers
+- **Testing utilities** - Test functions, mocks, utilities, custom matchers
 
 ## Installation
 
@@ -105,11 +100,13 @@ npm install --save-dev parseme
 
    ```bash
    npx parseme init
+   # or use the alias
+   npx parseme i
    ```
 
    You'll be prompted for:
    - Context directory path (default: `parseme-context`)
-   - Exclude patterns (default: `node_modules/**`, `.git/**` - patterns from `.gitignore` will be ignored by default as well)
+   - Exclude patterns (default: `node_modules/**`, `dist/**`, `.git/**` - in git repositories, additional patterns on top of git-tracked files)
 
    A minimal config file will be created with only your custom settings.
 
@@ -123,7 +120,7 @@ npm install --save-dev parseme
    ```json
    {
      "scripts": {
-       "parseme": "parseme"
+       "parseme": "parseme generate"
      }
    }
    ```
@@ -132,7 +129,9 @@ npm install --save-dev parseme
    ```bash
    npm run parseme
    # or
-   npx parseme
+   npx parseme generate
+   # or use the alias
+   npx parseme g
    ```
 
 This creates:
@@ -174,14 +173,12 @@ const config = {
   maxDepth: 10,
 
   // Git integration
-  includeGitInfo: true,
+  includeGitInfo: true, // Include git repository information in context
+  useGitForFiles: true, // Use git to discover files (respects .gitignore)
 
-  // AI-friendly size limits
+  // Size limits
   limits: {
-    maxLinesPerFile: 1000,
-    maxCharsPerFile: 50000,
-    maxFilesPerContext: 20,
-    truncateStrategy: 'truncate', // 'truncate' | 'split' | 'summarize'
+    maxFilesPerContext: 5000,
   },
 
   // Content sections (all default to true)
@@ -271,12 +268,13 @@ Configuration values are resolved in the following order (highest to lowest prio
 
 - `rootDir` - Project root directory (default: `process.cwd()`)
 - `analyzeFileTypes` - File extensions to analyze (default and supported: `['ts', 'tsx', 'js', 'jsx']`)
-- `excludePatterns` - Additional glob patterns to exclude on top of `.gitignore` patterns. Patterns from `.gitignore` are always included in exclusions, and `excludePatterns` adds to them.
+- `excludePatterns` - Additional glob patterns to exclude files. In git repositories, only git-tracked files are analyzed (respecting all `.gitignore` files automatically). Use `excludePatterns` to exclude additional files beyond what git ignores.
 - `maxDepth` - Maximum directory depth to traverse (default: `10`)
 
 #### Git Integration
 
-- `includeGitInfo` - Include git repository information (default: `true`)
+- `includeGitInfo` - Include git repository information in context files (default: `true`)
+- `useGitForFiles` - Use git to discover files, respecting .gitignore (default: `true`)
 
 #### Content Sections
 
@@ -298,12 +296,7 @@ Toggle which sections to include in the output (all default to `true`):
 
 #### Size Limits
 
-AI-friendly size limits to prevent token overflow:
-
-- `limits.maxLinesPerFile` - Maximum lines per file (default: `1000`)
-- `limits.maxCharsPerFile` - Maximum characters per file (default: `50000`)
-- `limits.maxFilesPerContext` - Maximum files per context (default: `20`)
-- `limits.truncateStrategy` - Strategy: `"truncate"`, `"split"`, or `"summarize"` (default: `"truncate"`)
+- `limits.maxFilesPerContext` - Maximum number of files to analyze (default: `5000`)
 
 ## Output Format
 
@@ -324,10 +317,12 @@ The context directory location can be customized via the `contextDir` configurat
 
 ```bash
 # Generate context (auto-detects config file)
-npx parseme
+npx parseme generate
+npx parseme g  # alias
 
 # Initialize configuration (JSON by default)
 npx parseme init
+npx parseme i  # alias
 
 # Initialize with TypeScript format
 npx parseme init --format ts
@@ -336,7 +331,7 @@ npx parseme init --format ts
 npx parseme init --format js
 
 # Use custom config file
-npx parseme --config custom.config.js
+npx parseme generate --config custom.config.js
 
 # If added to package.json scripts, use npm run
 npm run parseme
@@ -345,26 +340,36 @@ npm run parseme
 # Runs automatically after each commit
 
 # Override config with CLI flags
-npx parseme --output custom.md --context-dir docs/context --root ./src --no-git
+npx parseme generate --output custom.md --context-dir docs/context --root ./src
+
+# Disable git info generation (keeps git for file discovery)
+npx parseme generate --no-git-info
+
+# Disable git for file discovery (keeps git info generation)
+npx parseme generate --no-git-files
+
+# Disable both git info and git file discovery
+npx parseme generate --no-git-info --no-git-files
 
 # Specify file types and exclude patterns
-npx parseme --file-types ts js --exclude "**/*.test.ts"
+npx parseme generate --file-types ts js --exclude "**/*.test.ts"
 ```
 
 ### CLI Options
 
-#### Main Command (`parseme`)
+#### Generate Command (`parseme generate` or `parseme g`)
 
 - `-c, --config <path>` - Config file path
 - `-o, --output <path>` - Output file path
 - `-r, --root <path>` - Root directory to analyze
 - `--context-dir <path>` - Context directory path (default: parseme-context)
 - `--file-types <types...>` - File types to analyze (e.g., ts tsx js jsx)
-- `--exclude <patterns...>` - Exclude patterns (glob)
-- `--no-git` - Disable git information
+- `--exclude <patterns...>` - Additional exclude patterns (glob, in git repositories on top of git-tracked files)
+- `--no-git-info` - Disable git info generation (keeps git for file discovery)
+- `--no-git-files` - Disable git for file discovery (uses filesystem crawling instead)
 - `--max-depth <number>` - Maximum directory depth
 
-#### Init Command (`parseme init`)
+#### Init Command (`parseme init` or `parseme i`)
 
 - `-f, --force` - Overwrite existing config
 - `--format <format>` - Config format: json, ts, or js (default: json)
@@ -374,7 +379,7 @@ npx parseme --file-types ts js --exclude "**/*.test.ts"
 When running `parseme init` interactively (TTY, not CI), you'll be prompted to configure:
 
 - **Context directory** - Where to store context files (default: `parseme-context`)
-- **Exclude patterns** - Comma-separated glob patterns (default: `node_modules/**`, `.git/**` - patterns from `.gitignore` will be ignored by default as well)
+- **Exclude patterns** - Comma-separated glob patterns (default: `node_modules/**`, `dist/**`, `.git/**` - in git repositories, additional patterns on top of git-tracked files)
 
 After initialization, setup tips are displayed:
 
@@ -404,11 +409,6 @@ PARSEME automatically detects and provides specialized analysis for:
 - Plugin identification
 - Hook analysis
 
-### Koa & Hapi
-
-- Route and middleware detection
-- Framework-specific patterns
-
 ## Programmatic API
 
 You can also use PARSEME programmatically:
@@ -425,16 +425,48 @@ await generator.generateToFile('./output/PARSEME.md');
 
 ## Git Hook Integration
 
-Keep your AI context automatically updated by adding parseme as a post-commit hook:
+Keep your AI context automatically updated by integrating parseme with git hooks. The recommended setup uses three hooks to ensure context files always have git info locally but stay clean on remote:
+
+### Recommended Hook Setup
 
-### Manual Setup
+#### Manual Setup
 
 ```bash
-# Create and make executable
-echo '#!/bin/sh\npx parseme' > .git/hooks/post-commit
-chmod +x .git/hooks/post-commit
+# 1. Post-commit: Generate context with git info after each commit
+cat > .git/hooks/post-commit << 'EOF'
+#!/bin/sh
+
+npx parseme generate
+EOF
+
+# 2. Pre-push: Regenerate without git info and amend before pushing
+cat > .git/hooks/pre-push << 'EOF'
+#!/bin/sh
+
+# Regenerate without git info for clean remote state
+npx parseme generate --no-git-info
+
+# Stage parseme files (parseme-context/ may be different if configured)
+git add parseme-context/ PARSEME.md
+
+# Amend the commit with updated parseme files
+git commit --amend --no-edit --no-verify
+EOF
+
+# 3. Post-push: Restore git info locally after push completes
+cat > .git/hooks/post-push << 'EOF'
+#!/bin/sh
+
+# Regenerate with git info for local development
+npx parseme generate
+EOF
+
+# Make hooks executable
+chmod +x .git/hooks/post-commit .git/hooks/pre-push .git/hooks/post-push
 ```
 
+**Note:** If you've configured a custom `contextDir` (either in your config file or via the `--context-dir` CLI flag), update the `git add` path in the pre-push hook accordingly (e.g., `git add docs/context/ PARSEME.md`).
+
 ### Using Husky
 
 ```json
@@ -442,13 +474,25 @@ chmod +x .git/hooks/post-commit
 {
   "husky": {
     "hooks": {
-      "post-commit": "npx parseme"
+      "post-commit": "npx parseme generate",
+      "pre-push": "npx parseme generate --no-git-info && git add parseme-context/ PARSEME.md && git commit --amend --no-edit --no-verify",
+      "post-push": "npx parseme generate"
     }
   }
 }
 ```
 
-This automatically regenerates your AI context files after every commit, ensuring they're always up-to-date!
+**Note:** If using a custom `contextDir`, update the `git add` path to match your configuration.
+
+### How It Works
+
+1. **post-commit**: After you commit, parseme generates context files with git info (current branch, recent commits, git diff) for local development
+2. **pre-push**: Before pushing, parseme regenerates without git info (`--no-git-info` flag) and amends the commit to keep remote clean
+3. **post-push**: After push completes, parseme regenerates with git info again so your local working copy maintains full context
+
+The `--no-verify` flag in pre-push prevents an infinite loop by skipping hook execution on the amend.
+
+This automatically keeps your AI context files synchronized with your code while maintaining clean context on remote and detailed context locally!
 
 ## Requirements
 

package/dist/cli/cli.js

@@ -1,16 +1,18 @@
 #!/usr/bin/env node
 import { join } from 'path';
 import { Command } from 'commander';
-import { prompt } from './prompt.js';
 import { ParsemeConfig } from '../core/config.js';
 import { ParsemeGenerator } from '../core/generator.js';
+import { prompt } from '../utils/prompt.js';
 const program = new Command();
 async function promptForMissingConfig(config) {
     return { ...config };
 }
 program.name('parseme').description('AI Project Context Generator').version('0.1.0');
-// Main command - just run parseme
+// Generate command
 program
+    .command('generate')
+    .alias('g')
     .description('Generate project context using config file')
     .option('-c, --config <path>', 'Config file path')
     .option('-o, --output <path>', 'Output file path')
@@ -18,7 +20,8 @@ program
     .option('--context-dir <path>', 'Context directory path (default: parseme-context)')
     .option('--file-types <types...>', 'File types to analyze (e.g., ts tsx js jsx)')
     .option('--exclude <patterns...>', 'Exclude patterns (glob)')
-    .option('--no-git', 'Disable git information')
+    .option('--no-git-files', 'Disable git for file discovery')
+    .option('--no-git-info', 'Disable git info generation')
     .option('--max-depth <number>', 'Maximum directory depth', parseInt)
     .action(async (options) => {
     try {
@@ -29,7 +32,8 @@ program
             ...(options.contextDir && { contextDir: options.contextDir }),
             ...(options.fileTypes && { analyzeFileTypes: options.fileTypes }),
             ...(options.exclude && { excludePatterns: options.exclude }),
-            ...(options.git === false && { includeGitInfo: false }),
+            ...(options.gitFiles === false && { useGitForFiles: false }),
+            ...(options.gitInfo === false && { includeGitInfo: false }),
             ...(options.maxDepth && { maxDepth: options.maxDepth }),
         };
         const configFromFile = await ParsemeConfig.fromFile(options.config, {
@@ -56,8 +60,10 @@ program
         process.exit(1);
     }
 });
+// Init command
 program
     .command('init')
+    .alias('i')
     .description('Initialize parseme configuration')
     .option('-f, --force', 'Overwrite existing config')
     .option('--format <format>', 'Config format: json, ts, or js', 'json')
@@ -83,6 +89,10 @@ program
         }
         // Build config with only user-specified values
         const userConfig = {};
+        // Set defaults that would normally be prompted for
+        const defaultExcludePatterns = ['node_modules/**', 'dist/**', '.git/**'];
+        userConfig.contextDir = 'parseme-context';
+        userConfig.excludePatterns = defaultExcludePatterns;
         // Only prompt if interactive (TTY) and not in CI
         if (process.stdin.isTTY && !process.env.CI) {
             // Ask about context directory path
@@ -92,9 +102,8 @@ program
                 defaultValue: 'parseme-context',
             });
             // Ask about exclude patterns
-            const defaultExcludePatterns = ['node_modules/**', 'dist/**', '.git/**'];
             const excludePatternsAnswer = await prompt({
-                message: 'Exclude patterns (comma-separated glob patterns, patterns from .gitignore will be ignored by default as well)',
+                message: 'Exclude patterns (comma-separated glob patterns - in git repositories, additional to git-tracked files)',
                 defaultValue: defaultExcludePatterns.join(', '),
             });
             // Always set exclude patterns to what user entered (or defaults if they pressed enter)
@@ -109,8 +118,8 @@ program
         if (options.format === 'ts') {
             console.log('For TypeScript configs, ensure tsx or ts-node is available to load .ts files');
         }
-        console.log('Tip: Add "parseme": "parseme" to your package.json scripts for easier manual execution or hook integration');
-        console.log('Tip: Add parseme as a git hook to keep context auto-updated! See README for setup instructions.');
+        console.log('Tip: Add "parseme": "parseme generate" to your package.json scripts for easier manual execution or hook integration');
+        console.log('Tip: Add parseme as git hooks to keep context auto-updated! See README for recommended hook setup (post-commit, pre-push, post-push).');
         console.log('');
         console.log('Tip: Add this section to your README.md to help AI agents find the context:');
         console.log('');
@@ -125,31 +134,13 @@ program
         process.exit(1);
     }
 });
-// If no command and no args, run main action
+// If no command provided, show error and available commands
 if (process.argv.length <= 2) {
-    // Run the default action
-    (async () => {
-        try {
-            const configFromFile = await ParsemeConfig.fromFile(undefined, {
-                showWarnings: true,
-                throwOnNotFound: true,
-            });
-            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');
-        }
-        catch (error) {
-            if (error instanceof Error && error.message.includes('No configuration file found')) {
-                console.error(error.message);
-                process.exit(1);
-            }
-            console.error('Failed to generate context:', error);
-            process.exit(1);
-        }
-    })();
-}
-else {
-    program.parse();
+    console.error('No command specified.\n');
+    console.error('Available commands:');
+    console.error('  parseme generate (or parseme g) - Generate project context');
+    console.error('  parseme init (or parseme i)     - Initialize parseme configuration');
+    console.error('\nUse "parseme --help" for more information');
+    process.exit(1);
 }
+program.parse();

package/dist/core/analyzers/ast-analyzer.d.ts

@@ -2,7 +2,7 @@ import type { ParsemeConfig } from '../config.js';
 import type { FileAnalysis } from '../types.js';
 export declare class ASTAnalyzer {
     private readonly config;
-    private readonly ig;
+    private readonly fileCollector;
     private readonly patternDetector;
     constructor(config: ParsemeConfig);
     analyzeProject(rootDir: string): Promise<FileAnalysis[]>;

package/dist/core/analyzers/ast-analyzer.js

@@ -1,46 +1,32 @@
 import { readFile } from 'fs/promises';
-import { relative, extname } from 'path';
+import { join, extname } from 'path';
 import { parse } from '@babel/parser';
 import traverse from '@babel/traverse';
 import * as t from '@babel/types';
-import { glob } from 'glob';
-import ignore from 'ignore';
 import { PatternDetector } from './pattern-detector.js';
+import { FileCollector } from '../../utils/file-collector.js';
 export class ASTAnalyzer {
     config;
-    ig;
+    fileCollector;
     patternDetector;
     constructor(config) {
         this.config = config;
-        this.ig = ignore();
-        const configData = this.config.get();
-        this.ig.add(configData.excludePatterns || []);
+        this.fileCollector = new FileCollector(config);
         this.patternDetector = new PatternDetector();
     }
     async analyzeProject(rootDir) {
-        const configData = this.config.get();
-        const fileTypes = configData.analyzeFileTypes || ['ts', 'tsx', 'js', 'jsx'];
-        const patterns = fileTypes.map((type) => `**/*.${type}`);
-        const files = await glob(patterns, {
-            cwd: rootDir,
-            absolute: true,
-            ignore: configData.excludePatterns,
-        });
+        const result = await this.fileCollector.getCodeFiles(rootDir);
         const analyses = [];
-        for (const file of files) {
-            const relativePath = relative(rootDir, file);
-            // Skip if ignored
-            if (this.ig.ignores(relativePath)) {
-                continue;
-            }
+        for (const file of result.files) {
+            const filePath = join(rootDir, file);
             try {
-                const analysis = await this.analyzeFile(file, relativePath);
+                const analysis = await this.analyzeFile(filePath, file);
                 if (analysis) {
                     analyses.push(analysis);
                 }
             }
             catch (error) {
-                console.warn(`Failed to analyze ${relativePath}:`, error);
+                console.warn(`Failed to analyze ${file}:`, error);
                 // Continue with other files
             }
         }

package/dist/core/analyzers/framework-detector.d.ts

@@ -1,9 +1,7 @@
 import type { ProjectInfo, FrameworkInfo } from '../types.js';
 export declare class FrameworkDetector {
-    detect(projectInfo: ProjectInfo): Promise<FrameworkInfo>;
-    private detectExpress;
-    private detectFastify;
-    private detectNestJS;
-    private detectKoa;
-    private detectHapi;
+    private readonly frameworks;
+    detect(projectInfo: ProjectInfo): Promise<FrameworkInfo[]>;
+    private shouldDetect;
+    private buildFrameworkInfo;
 }