model-mesh-codemap 1.1.0

package/README.md

@@ -0,0 +1,461 @@
+# 📦 model-mesh-codemap
+
+Interactive CLI tool for generating project codemaps with multi-folder selection and batch processing.
+
+**Generate comprehensive code structure maps for your project with automatic framework detection, symbol extraction, and file statistics.**
+
+---
+
+## ✨ Features
+
+✅ **Interactive Folder Selection** — Visual discovery of all project folders with file counts  
+✅ **Multi-Folder Processing** — Generate codemaps for multiple folders in one execution  
+✅ **Flexible Selection** — Support ranges (`1-3`), mixed (`1,3-5`), and "all"  
+✅ **Framework Detection** — Automatically detects Rails, React, Express, Django, etc.  
+✅ **Multi-Language Support** — TypeScript, JavaScript, Ruby, ERB, JSON, YAML  
+✅ **Batch Operations** — Process multiple folders with success/failure summary  
+✅ **No Dependencies** — Uses only Node.js stdlib (compiled JS has zero runtime dependencies)  
+✅ **Type-Safe** — Full TypeScript with declaration files  
+
+---
+
+## 📦 Installation
+
+### Via npm (Global)
+```bash
+npm install -g model-mesh-codemap
+model-mesh-codemap                    # Interactive mode
+model-mesh-codemap app,src            # Direct mode
+```
+
+### Via npx (No Installation)
+```bash
+npx model-mesh-codemap                # Interactive mode
+npx model-mesh-codemap app,client     # Direct mode
+```
+
+### Local Installation
+```bash
+npm install --save-dev model-mesh-codemap
+npx model-mesh-codemap                # Use via npx
+```
+
+---
+
+## 🚀 Usage
+
+### Interactive Mode (Recommended)
+
+Run without arguments to get interactive folder selection:
+
+```bash
+$ model-mesh-codemap
+```
+
+**Output:**
+```
+🔍 Codemap Generation Tool
+
+📂 Available Folders:
+
+  1. app                   (180 files)
+  2. client                (95 files)
+  3. lib                   (42 files)
+  4. server                (67 files)
+  5. src                   (156 files)
+
+💡 Enter folder numbers to select (e.g., "1,2,4" or "all" or "1-3"):
+▶ Select folders: 1,2,5
+
+✅ Selected 3 folder(s):
+  • app (180 files)
+  • client (95 files)
+  • src (156 files)
+
+⏳ Generating codemaps...
+```
+
+### Direct Mode (Command-line Arguments)
+
+Specify folders directly:
+
+```bash
+# Single folder
+$ model-mesh-codemap app
+
+# Multiple folders (comma-separated)
+$ model-mesh-codemap app,client,src
+```
+
+### Selection Formats
+
+| Format | Example | Meaning |
+|--------|---------|---------|
+| Individual | `1` | Folder 1 only |
+| Multiple | `1,3,5` | Folders 1, 3, 5 |
+| Range | `1-3` | Folders 1, 2, 3 |
+| Mixed | `1,3-5` | Folder 1 + folders 3-5 |
+| All | `all` | All available folders |
+
+---
+
+## 📊 Output
+
+Codemaps are generated as JSON files in `.claude/codemaps/`:
+
+```
+.claude/codemaps/
+├── app.codemap.json
+├── client.codemap.json
+├── src.codemap.json
+└── ...
+```
+
+### Codemap Structure
+
+```json
+{
+  "timestamp": "2026-04-14T06:10:49.978Z",
+  "folderPath": "/path/to/project/app",
+  "relativePath": "app",
+  "statistics": {
+    "totalFiles": 180,
+    "totalLines": 45230,
+    "totalSymbols": 234,
+    "testFiles": 32,
+    "languages": {
+      "typescript": 120,
+      "tsx": 45,
+      "json": 8,
+      "yaml": 7
+    }
+  },
+  "files": [
+    {
+      "path": "app/models/user.ts",
+      "extension": "ts",
+      "language": "typescript",
+      "size": 2048,
+      "lines": 89,
+      "imports": ["express", "bcrypt"],
+      "exports": ["User", "UserService"],
+      "symbols": [
+        {
+          "name": "UserService",
+          "type": "class",
+          "line": 15
+        }
+      ]
+    }
+    // ... more files
+  ],
+  "structure": {
+    "name": "app",
+    "type": "directory",
+    "path": "app",
+    "children": [
+      {
+        "name": "models",
+        "type": "directory",
+        "children": [...]
+      }
+    ]
+  },
+  "metadata": {
+    "generatedBy": "model-mesh-codemap",
+    "version": "1.0.0"
+  }
+}
+```
+
+---
+
+## 🔧 Supported Languages
+
+- **TypeScript/JavaScript** — Classes, interfaces, exports, imports
+- **Ruby** — Classes, methods, modules, constants
+- **ERB** — Template includes, embedded Ruby
+- **JSON** — Top-level keys and structure
+- **YAML** — Configuration keys
+
+---
+
+## 🎯 Use Cases
+
+### 1. **Onboarding New Developers**
+Generate codemaps to help new team members understand project structure.
+
+```bash
+model-mesh-codemap                    # Show all folders
+# Select key folders: "app,config,lib"
+```
+
+### 2. **AI Model Context**
+Use codemaps with Claude AI for context-aware code assistance.
+
+```bash
+# Generate codemap for your project
+model-mesh-codemap src
+
+# Then provide .claude/codemaps/src.codemap.json to Claude
+```
+
+### 3. **Documentation Generation**
+Extract code structure for automated documentation.
+
+```bash
+model-mesh-codemap app,lib,config
+# Codemaps are JSON-parseable for doc generation
+```
+
+### 4. **Code Audits & Analysis**
+Analyze file counts, language distribution, and structure.
+
+```bash
+model-mesh-codemap                    # Interactive selection
+# Review statistics and framework detection
+```
+
+---
+
+## 📋 Examples
+
+### Example 1: Rails + React Project
+
+```bash
+$ model-mesh-codemap
+
+📂 Available Folders:
+  1. app                   (245 files)
+  2. client                (178 files)
+  3. config                (42 files)
+  4. db                    (8 files)
+  5. lib                   (34 files)
+
+▶ Select folders: 1,2
+# Generates app.codemap.json and client.codemap.json
+```
+
+### Example 2: Microservices
+
+```bash
+$ model-mesh-codemap services,shared,config
+
+# Batch process multiple folders with direct argument
+✅ Successful: 3
+❌ Failed: 0
+```
+
+### Example 3: Integration with Node Scripts
+
+```javascript
+const { exec } = require('child_process');
+
+// Generate codemaps programmatically
+exec('model-mesh-codemap src,lib', (error, stdout) => {
+  if (error) console.error(error);
+  console.log('Codemaps generated!');
+});
+```
+
+---
+
+## ⚙️ Configuration
+
+The tool automatically:
+- Discovers folders in your project root
+- Filters ignored directories (node_modules, .git, .claude, dist, etc.)
+- Counts files efficiently (1000 file limit per folder for performance)
+- Sorts folders by common names (app, src, client, server, lib first)
+
+No configuration file needed — works out of the box!
+
+---
+
+## 🔍 Ignored Directories
+
+The following directories are automatically filtered:
+
+```
+node_modules, .git, .claude, dist, build, coverage,
+.next, tmp, .cache, .nuxt, out, .env, .env.local,
+.env.*.local, .idea, .vscode, .DS_Store, Thumbs.db
+```
+
+---
+
+## 🚨 Troubleshooting
+
+### "No folders found"
+The tool couldn't discover any folders. Check that:
+- You're running from your project root
+- You have folders at the root level (not hidden with dot-prefix)
+
+### "Module not found" Error
+Ensure Node.js 18+ is installed:
+```bash
+node --version  # Should be v18.0.0 or higher
+```
+
+### Codemap files are empty
+This happens if the target folders are empty or contain no supported file types. The tool works best with:
+- Source code files (ts, tsx, js, jsx, rb, py, etc.)
+- Configuration files (json, yaml, yml)
+- Template files (erb, html)
+
+---
+
+## 📈 Performance
+
+- **Scanning:** ~1 second per 100 files
+- **Parsing:** Regex-based, very fast
+- **Output:** Compact JSON (30KB per 200 files)
+- **Memory:** < 50MB for typical projects
+
+**Batch Processing:** Generate 5 codemaps in ~5-10 seconds
+
+---
+
+## 🔐 Security & Privacy
+
+✅ **No external API calls** — All processing local  
+✅ **No data collection** — Runs entirely on your machine  
+✅ **Open source** — Full transparency  
+✅ **Standalone** — Zero runtime dependencies (compiled)  
+
+---
+
+## 📚 Advanced Usage
+
+### Programmatic API
+
+```typescript
+import { CodemapCLI } from 'model-mesh-codemap';
+
+const cli = new CodemapCLI(process.cwd());
+
+// Interactive mode
+await cli.run();
+
+// Direct mode with folders
+await cli.run('app,src,client');
+```
+
+### Integration with Other Tools
+
+```bash
+# Use output in Node.js scripts
+const fs = require('fs');
+const codemap = JSON.parse(
+  fs.readFileSync('.claude/codemaps/app.codemap.json', 'utf-8')
+);
+
+console.log(`Total files: ${codemap.statistics.totalFiles}`);
+console.log(`Frameworks: ${codemap.frameworks}`);
+```
+
+---
+
+## 🛠️ Development
+
+### Build from Source
+
+```bash
+# Clone repository
+git clone https://github.com/ioit-solutions/model-mesh.git
+cd model-mesh
+
+# Install dependencies
+npm install
+
+# Build TypeScript
+npm run build
+
+# Test
+npm run test
+```
+
+### Development Mode
+
+```bash
+# Run directly from TypeScript
+npm run dev
+
+# Or use tsx
+npx tsx ./.claude/cli/codemap.ts
+```
+
+---
+
+## 📝 What's Included
+
+- ✅ Interactive CLI with folder discovery
+- ✅ Multi-selection support (ranges, mixed, all)
+- ✅ Multi-language symbol extraction
+- ✅ Framework auto-detection
+- ✅ Batch processing with error handling
+- ✅ TypeScript declarations
+- ✅ Source maps for debugging
+- ✅ Zero external dependencies
+
+---
+
+## 📦 Package Contents
+
+```
+model-mesh-codemap/
+├── dist/cli/
+│   ├── bin.js                    # Executable entry point
+│   ├── codemap.js               # Main CLI class
+│   ├── codemap-generator.js      # Core scanning engine
+│   ├── folder-selector.js        # Interactive folder selection
+│   ├── language-parsers.js       # Symbol extraction
+│   ├── ignore-rules.js           # File filtering
+│   ├── types.js                  # Type definitions
+│   └── *.d.ts                    # TypeScript declarations
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+---
+
+## 📄 License
+
+MIT
+
+---
+
+## 🤝 Contributing
+
+Contributions welcome! 
+
+Areas for improvement:
+- [ ] Additional language support (Go, Rust, Python, Java)
+- [ ] Progress bar for large folders
+- [ ] Watch mode for incremental updates
+- [ ] HTML report generation
+- [ ] Integration with popular IDEs (VS Code extension)
+- [ ] Performance optimizations for large codebases
+
+---
+
+## 📞 Support
+
+- **Issues**: [GitHub Issues](https://github.com/ioit-solutions/model-mesh/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/ioit-solutions/model-mesh/discussions)
+- **Documentation**: [model-mesh docs](https://github.com/ioit-solutions/model-mesh)
+
+---
+
+## 🌟 Quick Links
+
+- **GitHub**: [ioit-solutions/model-mesh](https://github.com/ioit-solutions/model-mesh)
+- **NPM**: [model-mesh-codemap](https://npmjs.com/package/model-mesh-codemap)
+- **Documentation**: [docs/codemap](https://github.com/ioit-solutions/model-mesh/docs/codemap)
+
+---
+
+**Made with ❤️ by IOIT Solutions**
+
+*Transform your project structure into actionable intelligence.*

package/dist/bin.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/**
+ * CLI Entry Point for model-mesh-codemap
+ * Usage:
+ *   npx model-mesh-codemap                    # Interactive mode
+ *   npx model-mesh-codemap app,src,client     # Direct mode with multiple folders
+ *   npx model-mesh-codemap app                # Single folder
+ */
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AAEA;;;;;;GAMG"}

package/dist/bin.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * CLI Entry Point for model-mesh-codemap
+ * Usage:
+ *   npx model-mesh-codemap                    # Interactive mode
+ *   npx model-mesh-codemap app,src,client     # Direct mode with multiple folders
+ *   npx model-mesh-codemap app                # Single folder
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const codemap_1 = require("./codemap");
+const projectRoot = process.cwd();
+const folderArg = process.argv[2];
+const cli = new codemap_1.CodemapCLI(projectRoot);
+cli.run(folderArg).catch(error => {
+    console.error('❌ Fatal error:', error);
+    process.exit(1);
+});
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";;AAEA;;;;;;GAMG;;AAGH,uCAAuC;AAEvC,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;AAClC,MAAM,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAElC,MAAM,GAAG,GAAG,IAAI,oBAAU,CAAC,WAAW,CAAC,CAAC;AAExC,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE;IAC/B,OAAO,CAAC,KAAK,CAAC,gBAAgB,EAAE,KAAK,CAAC,CAAC;IACvC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/codemap-generator.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Core Codemap Generator
+ * Scans directories, extracts metadata, generates codemaps
+ */
+import { FolderCodemap, CodemapConfig } from './types.js';
+export declare class CodemapGenerator {
+    private ignoreRules;
+    private config;
+    private projectRoot;
+    constructor(projectRoot: string, customConfig?: Partial<CodemapConfig>);
+    generate(folderPath: string): Promise<FolderCodemap>;
+    private scanDirectory;
+    private extractFileMetadata;
+    private detectLanguage;
+    private isTestFile;
+    private getLanguageStats;
+    private buildDirectoryTree;
+}
+//# sourceMappingURL=codemap-generator.d.ts.map

package/dist/codemap-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codemap-generator.d.ts","sourceRoot":"","sources":["../src/codemap-generator.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,OAAO,EACL,aAAa,EAGb,aAAa,EACd,MAAM,YAAY,CAAC;AAEpB,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,WAAW,CAAS;gBAEhB,WAAW,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC;IAwBhE,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;YAiD5C,aAAa;YAkCb,mBAAmB;IAwCjC,OAAO,CAAC,cAAc;IAkBtB,OAAO,CAAC,UAAU;IAalB,OAAO,CAAC,gBAAgB;YAUV,kBAAkB;CA2CjC"}