@parseme/cli 0.0.3 → 0.0.5

package/README.md

@@ -6,7 +6,7 @@ PARSEME analyzes your TypeScript/JavaScript projects and generates a PARSEME.md
 
 ## Development Status
 
-**This project is currently in active development and beta phase.**
+**This project is currently in active development and pre-alpha phase.**
 
 The core functionality is working, but expect:
 
@@ -25,97 +25,68 @@ Your feedback is **highly appreciated** and helps shape the future of this tool!
 
 ## Features
 
-- **Universal Pattern Detection** - Dynamic code analysis that works across any JavaScript/TypeScript framework
 - **Project Analysis** - AST-based code analysis with automatic endpoint, component, and service discovery
-- **Framework Agnostic** - No framework-specific dependencies - works with any codebase structure
-- **Configurable Output** - Multi-file context generation optimized for AI assistants
+- **Universal Pattern Detection** - Dynamic code analysis that works across many JavaScript/TypeScript frameworks
 - **Git Integration** - Includes repository status and change tracking
-- **Highly Configurable** - Comprehensive configuration options via JavaScript, TypeScript, or JSON
-- **Dev Tool Integration** - Works seamlessly as an npm script
+- **Configurable** - Comprehensive configuration options via JavaScript, TypeScript, or JSON
+- **Dev Tool Integration** - Works seamlessly as a npm script
 
-### 🔍 **What PARSEME Detects**
+### **What PARSEME Detects**
 
 PARSEME uses AST analysis to identify:
 
-- **📡 API Endpoints** - HTTP routes, GraphQL resolvers, RPC methods
-- **🧩 Components** - UI components across all major frameworks
-- **⚙️ Services** - Business logic classes and service functions
-- **📋 Data Models** - Interfaces, types, schemas, DTOs
-- **🔗 Middleware** - Request/response handlers and interceptors
-- **🛠️ Utilities** - Helper functions, hooks, composables
-- **📁 Project Structure** - Organized by detected patterns and purpose
+- **API Endpoints** - HTTP routes, GraphQL resolvers, RPC methods
+- **Components** - UI components across all major frameworks
+- **Services** - Business logic classes and service functions
+- **Data Models** - Interfaces, types, schemas, DTOs
+- **Middleware** - Request/response handlers and interceptors
+- **Utilities** - Helper functions, hooks, composables
+- **Project Structure** - Organized by detected patterns and purpose
 
 ## **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
 
 ## Supported Projects
 
-PARSEME aims to automatically analyse any JavaScript or TypeScript project:
+PARSEME aims to automatically analyse any JavaScript or TypeScript project like:
 
-### 🖥️ **Backend APIs**
+### **Backend APIs**
 
 - **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**
+### **Frontend Applications**
 
 - **React** - Components (functional & class), hooks, JSX patterns
 - **Vue.js** - Components (Composition & Options API), composables
 - **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**
-
-- **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
-
-### 🛠️ **Development Tools**
-
-- **CLI applications** - Command-line tools and scripts
-- **Build tools** - Webpack plugins, Vite configurations
-- **Desktop applications** - Electron, Tauri apps
-- **Testing utilities** - Jest plugins, test helpers
-
-### 🏗️ **Fullstack Frameworks**
+### **Fullstack Frameworks**
 
 - **Next.js** - Pages, API routes, middleware, components
-- **Nuxt.js** - Vue-based fullstack applications
-- **SvelteKit** - Svelte-based fullstack applications
-- **Remix** - React-based fullstack applications
--
-
-## Development Status
+- **Nuxt.js** - Pages, server routes, composables, components
 
-**This project is currently in active development and beta phase.**
-
-The core functionality is working, but expect:
-
-- Breaking changes in configuration format
-- API modifications as the interface gets refined
-- Additional features being added regularly
-- Possible bugs and edge cases
+### **Packages & Libraries**
 
-### Feedback Welcome!
+- **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
 
-Your feedback is **highly appreciated** and helps shape the future of this tool! Please:
+### **Development Tools**
 
-- [Report bugs or issues](https://github.com/citrus551/parseme-modules/issues)
-- [Suggest features or improvements](https://github.com/citrus551/parseme-modules/discussions)
-- For other inquiries, contact: mail.citrus551@passmail.net
-- Share your use cases and experiences
-- Star the repo if you find it useful
+- **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
 
@@ -129,14 +100,27 @@ npm install --save-dev parseme
 
    ```bash
    npx parseme init
+   # or use the alias
+   npx parseme i
    ```
 
-2. **Add to your package.json scripts**:
+   You'll be prompted for:
+   - Context directory path (default: `parseme-context`)
+   - 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.
+
+   Setup tips will be displayed:
+   - How to add parseme script to package.json
+   - How to integrate with git hooks
+   - README section to help AI agents find context
+
+2. **Add to your package.json scripts** (optional, for easier execution):
 
    ```json
    {
      "scripts": {
-       "parseme": "parseme"
+       "parseme": "parseme generate"
      }
    }
    ```
@@ -144,34 +128,59 @@ npm install --save-dev parseme
 3. **Generate context**:
    ```bash
    npm run parseme
+   # or
+   npx parseme generate
+   # or use the alias
+   npx parseme g
    ```
 
-This will create a `PARSEME.md` file and a `parseme-context/` directory with comprehensive project context.
+This creates:
+
+- `PARSEME.md` - Main overview with links to context files
+- `parseme-context/` - Structured data files (AST, dependencies, routes, git info)
 
 ## Configuration
 
 PARSEME supports multiple configuration formats with automatic discovery and priority handling.
 
+The `parseme init` command creates a minimal config with only your custom settings. Defaults are applied automatically at runtime.
+
+**Minimal config example** (created by `parseme init`):
+
 ```javascript
 /** @type {import('parseme').ParsemeConfigFile} */
-export default {
+const config = {
+  contextDir: 'parseme-context',
+  excludePatterns: ['node_modules/**', '.git/**'],
+};
+
+export default config;
+```
+
+**Full config example** (all available options):
+
+```javascript
+/** @type {import('parseme').ParsemeConfigFile} */
+const config = {
   // Output settings
   outputPath: 'PARSEME.md',
-  contextDir: 'parseme-context', // or "docs/context", "/absolute/path"
+  contextDir: 'parseme-context',
 
   // Analysis settings
-  includePatterns: ['src/**/*.ts', 'src/**/*.js', 'package.json'],
-  excludePatterns: ['node_modules/**', 'dist/**', '**/*.test.ts'],
+  rootDir: './',
+  analyzeFileTypes: ['ts', 'tsx', 'js', 'jsx'],
+  excludePatterns: ['**/*.test.ts', 'dist/**'],
+  maxDepth: 10,
+
+  // Git integration
+  includeGitInfo: true,
 
-  // AI-friendly size limits
+  // Size limits
   limits: {
-    maxLinesPerFile: 1000,
-    maxCharsPerFile: 50000,
-    maxFilesPerContext: 20,
-    truncateStrategy: 'split', // or 'truncate'
+    maxFilesPerContext: 5000,
   },
 
-  // Content sections
+  // Content sections (all default to true)
   sections: {
     overview: true,
     architecture: true,
@@ -180,46 +189,68 @@ export default {
     git: true,
     fileStructure: true,
   },
+
+  // Style options
+  style: {
+    includeLineNumbers: false,
+    includeFileStats: true,
+    groupByType: true,
+    sortOrder: 'type', // 'alphabetical' | 'type' | 'size'
+  },
 };
+
+export default config;
 ```
 
 ### Configuration File Formats & Priority
 
 PARSEME supports three configuration formats with the following priority:
 
-1. **TypeScript** (`.ts`) - `parseme.config.ts`, `.parsemerc.ts`
-2. **JavaScript** (`.js`) - `parseme.config.js`, `.parsemerc.js`
-3. **JSON** (`.json`) - `parseme.config.json`, `.parsemerc.json`, `.parsemerc`
+1. **JSON** (`.json`) - `parseme.config.json`, `.parsemerc.json`, `.parsemerc`
+2. **TypeScript** (`.ts`) - `parseme.config.ts`, `.parsemerc.ts`
+3. **JavaScript** (`.js`) - `parseme.config.js`, `.parsemerc.js`
+
+#### Example JSON Configuration
+
+```json
+{
+  "contextDir": "parseme-context",
+  "excludePatterns": ["node_modules/**", "dist/**", ".git/**"]
+}
+```
 
-#### TypeScript Configuration
+#### Example TypeScript Configuration
 
 ```typescript
 import type { ParsemeConfigFile } from 'parseme';
 
 const config: ParsemeConfigFile = {
-  outputPath: 'PARSEME.md',
-  includePatterns: ['src/**/*.ts'],
+  contextDir: 'parseme-context',
+  excludePatterns: ['node_modules/**', 'dist/**', '.git/**'],
   // ... other options
 };
 
 export default config;
 ```
 
-#### JSON Configuration
+#### Example JavaScript Configuration
 
-```json
-{
-  "outputPath": "PARSEME.md",
-  "contextDir": "parseme-context",
-  "includePatterns": ["src/**/*.ts"]
-}
+```javascript
+/** @type {import('parseme').ParsemeConfigFile} */
+const config = {
+  contextDir: 'parseme-context',
+  excludePatterns: ['node_modules/**', 'dist/**', '.git/**'],
+  // ... other options
+};
+
+export default config;
 ```
 
 ### Configuration Priority
 
 Configuration values are resolved in the following order (highest to lowest priority):
 
-1. **CLI flags** - `--output`, `--root`, `--include`, etc.
+1. **CLI flags** - `--output`, `--root`, `--config`, etc.
 2. **Config file** - Based on file format priority above
 3. **Default values** - Built-in sensible defaults
 
@@ -229,52 +260,54 @@ Configuration values are resolved in the following order (highest to lowest prio
 
 #### Output Settings
 
-- `outputPath` - Where to save the main PARSEME.md file (default: "PARSEME.md")
-- `contextDir` - Directory for detailed context files (default: "parseme-context")
+- `outputPath` - Where to save the main PARSEME.md file (default: `"PARSEME.md"`)
+- `contextDir` - Directory for detailed context files (default: `"parseme-context"`)
 
 #### Analysis Settings
 
-- `rootDir` - Project root directory (default: current directory)
-- `includePatterns` - Glob patterns for files to analyze
-- `excludePatterns` - Glob patterns for files to ignore
-- `maxDepth` - Maximum directory depth to traverse
+- `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 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`)
 
-#### Framework Settings
+#### Git Integration
 
-Configure framework-specific analysis:
-
-- **Express**: `detectMiddleware`, `documentRoutes`
-- **NestJS**: `includeDecorators`, `documentModules`
-- **Fastify**: `includePlugins`
+- `includeGitInfo` - Include git repository information (default: `true`)
 
 #### Content Sections
 
-Toggle which sections to include:
+Toggle which sections to include in the output (all default to `true`):
 
-- `overview` - Project overview and metadata
-- `architecture` - File type breakdown
-- `routes` - API endpoints and routing
-- `dependencies` - Package dependencies
-- `git` - Repository information
-- `fileStructure` - Detailed file listing
+- `sections.overview` - Project overview and metadata
+- `sections.architecture` - File type breakdown
+- `sections.routes` - API endpoints and routing
+- `sections.dependencies` - Package dependencies
+- `sections.git` - Repository information
+- `sections.fileStructure` - Detailed file listing
 
 #### Style Options
 
-- `includeLineNumbers` - Add line numbers to code references
-- `includeFileStats` - Include file statistics
-- `groupByType` - Group files by detected type
-- `sortOrder` - "alphabetical", "type", or "size"
+- `style.includeLineNumbers` - Add line numbers to code references (default: `false`)
+- `style.includeFileStats` - Include file statistics (default: `true`)
+- `style.groupByType` - Group files by detected type (default: `true`)
+- `style.sortOrder` - Sort order: `"alphabetical"`, `"type"`, or `"size"` (default: `"type"`)
+
+#### Size Limits
+
+- `limits.maxFilesPerContext` - Maximum number of files to analyze (default: `5000`)
 
 ## Output Format
 
-PARSEME always generates multi-file output:
+PARSEME always generates the following output files:
 
-- `PARSEME.md` - Main overview and summary (Markdown format)
-- Context directory (default: `parseme-context/`) with detailed JSON files:
-  - `structure.json` - Detailed AST analysis with file exports, imports, functions, and classes
-  - `routes.json` - API routes documentation with methods, paths, and handlers
-  - `dependencies.json` - Production dependency analysis with package versions
-  - `git.json` - Git repository information with branch, status, and changed files
+- `PARSEME.md` - Main overview with links to context files (Markdown)
+- Context directory (default: `parseme-context/`) with structured data files:
+  - `files.md` - Complete list of analyzed files (Markdown)
+  - `structure.json` - AST analysis with exports, imports, functions, and classes (JSON)
+  - `api-endpoints.json` - API routes with methods, paths, and handlers (JSON, only if routes detected)
+  - `dependencies.json` - Production dependencies with versions (JSON)
+  - `framework.json` - Framework details if detected (JSON, optional)
+  - `gitDiff.md` - Git diff statistics from generation time (Markdown, if git enabled)
 
 The context directory location can be customized via the `contextDir` configuration option.
 
@@ -282,60 +315,65 @@ 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 (JavaScript by default)
+# Initialize configuration (JSON by default)
 npx parseme init
+npx parseme i  # alias
 
 # Initialize with TypeScript format
 npx parseme init --format ts
 
-# Initialize with JSON format
-npx parseme init --format json
+# Initialize with JavaScript format
+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
+
+# Auto-generate context with git hooks (when configured)
+# 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 --no-git
 
-# Include/exclude patterns
-npx parseme --include "src/**/*.ts" --exclude "**/*.test.ts"
+# Specify file types and exclude patterns
+npx parseme generate --file-types ts js --exclude "**/*.test.ts"
 ```
 
 ### CLI Options
 
+#### 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)
-- `--include <patterns...>` - Include patterns (glob)
-- `--exclude <patterns...>` - Exclude patterns (glob)
+- `--file-types <types...>` - File types to analyze (e.g., ts tsx js jsx)
+- `--exclude <patterns...>` - Additional exclude patterns (glob, in git repositories on top of git-tracked files)
 - `--no-git` - Disable git information
 - `--max-depth <number>` - Maximum directory depth
-- `--no-readme-suggestion` - Disable README.md section suggestion
 
-### Interactive Configuration
-
-When the README suggestion setting is not configured and you're running parseme interactively, you'll be prompted to configure:
-
-- **README suggestion** - Whether to show the README.md section suggestion for AI agents
+#### Init Command (`parseme init` or `parseme i`)
 
-The prompt is automatically disabled in:
+- `-f, --force` - Overwrite existing config
+- `--format <format>` - Config format: json, ts, or js (default: json)
 
-- CI environments (when `CI=true`)
-- Non-interactive terminals (no TTY)
-- When the value is explicitly provided via CLI flags or config files
+### Interactive Configuration
 
-Example interactive session:
+When running `parseme init` interactively (TTY, not CI), you'll be prompted to configure:
 
-```
-$ npx parseme
+- **Context directory** - Where to store context files (default: `parseme-context`)
+- **Exclude patterns** - Comma-separated glob patterns (default: `node_modules/**`, `dist/**`, `.git/**` - in git repositories, additional patterns on top of git-tracked files)
 
-Show README.md section suggestion for AI agents? [y]: y
+After initialization, setup tips are displayed:
 
-Context generated successfully
-```
+- Package.json script suggestion
+- Git hook integration suggestion
+- README.md section suggestion for AI agents
 
 ## Framework Support
 
@@ -350,7 +388,7 @@ PARSEME automatically detects and provides specialized analysis for:
 ### NestJS
 
 - Controller and decorator analysis
-- Module structure detection
+- Module structure detection w
 - Dependency injection mapping
 
 ### Fastify
@@ -359,49 +397,6 @@ PARSEME automatically detects and provides specialized analysis for:
 - Plugin identification
 - Hook analysis
 
-### Koa & Hapi
-
-- Route and middleware detection
-- Framework-specific patterns
-
-## Integration Examples
-
-### Basic Express Project
-
-```javascript
-// parseme.config.js
-export default {
-  includePatterns: ['src/**/*.js', 'routes/**/*.js', 'middleware/**/*.js'],
-  frameworks: {
-    express: {
-      detectMiddleware: true,
-      documentRoutes: true,
-    },
-  },
-};
-```
-
-### TypeScript NestJS Project
-
-```javascript
-// parseme.config.js
-export default {
-  includePatterns: ['src/**/*.ts', '!src/**/*.spec.ts'],
-  frameworks: {
-    nestjs: {
-      includeDecorators: true,
-      documentModules: true,
-    },
-  },
-  sections: {
-    overview: true,
-    architecture: true,
-    routes: true,
-    dependencies: true,
-  },
-};
-```
-
 ## Programmatic API
 
 You can also use PARSEME programmatically:
@@ -424,7 +419,7 @@ Keep your AI context automatically updated by adding parseme as a post-commit ho
 
 ```bash
 # Create and make executable
-echo '#!/bin/sh\nnpx parseme' > .git/hooks/post-commit
+echo '#!/bin/sh\npx parseme generate' > .git/hooks/post-commit
 chmod +x .git/hooks/post-commit
 ```
 
@@ -435,7 +430,7 @@ chmod +x .git/hooks/post-commit
 {
   "husky": {
     "hooks": {
-      "post-commit": "npx parseme"
+      "post-commit": "npx parseme generate"
     }
   }
 }