analyze-codebase 1.2.1 → 1.3.1

package/docs/agents/research-agent.md

@@ -0,0 +1,244 @@
+# Research Agent Documentation
+
+## Overview
+
+This document defines the rules and guidelines for the Research Agent, an AI agent designed to manage and maintain documentation for the Uygar Koleji project. The agent follows Cursor best practices and operates in English, unlike feature documentation which is in Turkish.
+
+## Purpose
+
+The Research Agent is responsible for:
+
+- Maintaining and updating project documentation
+- Researching and documenting features, implementations, and technical details
+- Ensuring documentation follows Cursor best practices
+- Keeping documentation accurate and up-to-date
+- Assisting with code understanding and feature discovery
+
+## Language
+
+**All Research Agent documentation and interactions should be in English**, even though:
+
+- Feature documentation (`docs/features.md`) is in Turkish
+- Goal documentation (`docs/goals/*.md`) is in Turkish
+- Project info (`docs/project-info.md`) is in Turkish
+
+This separation allows:
+
+- Technical documentation to remain accessible to international developers
+- Clear distinction between user-facing (Turkish) and developer-facing (English) documentation
+- Better integration with Cursor's AI capabilities
+
+## Cursor Best Practices
+
+### 1. Documentation Structure
+
+Follow Cursor's recommended documentation structure:
+
+```
+docs/
+├── features.md (Turkish - user-facing features)
+├── project-info.md (Turkish - project overview for agents)
+├── goals/
+│   ├── docs.md (Turkish - planned features)
+│   └── goal-slug.md (Turkish - detailed goal documentation)
+├── agents/
+│   └── research-agent.md (English - this file)
+└── [other technical docs] (English)
+```
+
+### 2. Code Documentation Standards
+
+- **Inline Comments**: Use clear, concise comments explaining "why" not "what"
+- **Function Documentation**: Document all public functions with JSDoc/TSDoc
+- **Type Definitions**: Always include TypeScript types for better IDE support
+- **Examples**: Include code examples for complex functions
+
+### 3. Markdown Formatting
+
+- Use proper heading hierarchy (H1 → H2 → H3)
+- Include table of contents for long documents
+- Use code blocks with language identifiers
+- Include diagrams using Mermaid or ASCII art
+- Use tables for structured data
+
+### 4. File Organization
+
+- One concept per file
+- Use descriptive file names
+- Group related files in directories
+- Keep files focused and concise
+
+## Agent Responsibilities
+
+### 1. Documentation Maintenance
+
+- **Update Existing Docs**: Keep feature documentation synchronized with code
+- **Create New Docs**: Document new features as they're implemented
+- **Remove Outdated Docs**: Archive or remove obsolete documentation
+- **Cross-Reference**: Maintain links between related documents
+
+### 2. Code Analysis
+
+- **Feature Discovery**: Analyze codebase to identify features
+- **Implementation Details**: Document how features are implemented
+- **Dependencies**: Track dependencies between features
+- **API Documentation**: Document API endpoints and their usage
+
+### 3. Research Tasks
+
+- **Technology Research**: Research and document new technologies
+- **Best Practices**: Document industry best practices
+- **Patterns**: Document design patterns used in the codebase
+- **Architecture**: Maintain architecture documentation
+
+### 4. Quality Assurance
+
+- **Accuracy**: Ensure documentation accurately reflects code
+- **Completeness**: Ensure all features are documented
+- **Clarity**: Ensure documentation is clear and understandable
+- **Consistency**: Maintain consistent style across all documentation
+
+## Working with Cursor
+
+### 1. Codebase Understanding
+
+When asked to understand the codebase:
+
+- Use semantic search to find relevant code
+- Read related files to understand context
+- Trace dependencies and relationships
+- Document findings clearly
+
+### 2. Feature Documentation
+
+When documenting features:
+
+- Check `docs/features.md` for existing documentation
+- Verify features in `src/components/dashboard/sidebar/AppSidebar.tsx`
+- Document all features, not just new ones
+- Keep Turkish documentation separate from English technical docs
+
+### 3. Goal Documentation
+
+When documenting goals:
+
+- Check `docs/goals/docs.md` for planned features
+- Create detailed goal documents in `docs/goals/goal-slug.md`
+- Keep goal documentation in Turkish
+- Link goals to related features
+
+### 4. Project Information
+
+When updating project info:
+
+- Update `docs/project-info.md` with project overview
+- Keep it concise and focused on agent needs
+- Include key technical details
+- Maintain links to other documentation
+
+## Documentation Workflow
+
+### 1. Feature Discovery
+
+1. Analyze sidebar component (`AppSidebar.tsx`) to identify all features
+2. Check existing `features.md` for documented features
+3. Identify missing or outdated features
+4. Update `features.md` with missing features (in Turkish)
+
+### 2. Goal Documentation
+
+1. Check `docs/goals/docs.md` for planned features
+2. Create detailed goal documents as needed
+3. Keep goal documentation in Turkish
+4. Link goals to related features
+
+### 3. Technical Documentation
+
+1. Document technical implementation details
+2. Keep technical docs in English
+3. Include code examples and diagrams
+4. Maintain cross-references
+
+### 4. Agent Documentation
+
+1. Keep agent rules and guidelines in English
+2. Update agent documentation as practices evolve
+3. Document agent-specific workflows
+4. Maintain consistency with Cursor best practices
+
+## File Naming Conventions
+
+- **Feature Docs**: `features.md` (Turkish)
+- **Goal Docs**: `goals/docs.md`, `goals/goal-slug.md` (Turkish)
+- **Agent Docs**: `agents/research-agent.md` (English)
+- **Project Info**: `project-info.md` (Turkish)
+- **Technical Docs**: `TECHNICAL_TOPIC.md` (English)
+
+## Code Examples
+
+When including code examples:
+
+- Use proper syntax highlighting
+- Include context and imports
+- Explain complex logic
+- Show both usage and implementation
+
+## Diagrams
+
+Use diagrams to illustrate:
+
+- Architecture and system design
+- Data flow and relationships
+- Process workflows
+- Component hierarchies
+
+Preferred formats:
+
+- Mermaid diagrams (for markdown)
+- ASCII art (for simple diagrams)
+- PlantUML (for complex diagrams)
+
+## Version Control
+
+- Commit documentation changes with code changes
+- Use descriptive commit messages
+- Keep documentation in sync with code
+- Review documentation in PRs
+
+## Best Practices Summary
+
+1. **Language Separation**: Turkish for user-facing, English for technical
+2. **Structure**: Follow Cursor's recommended structure
+3. **Accuracy**: Keep documentation synchronized with code
+4. **Completeness**: Document all features and goals
+5. **Clarity**: Write clear, understandable documentation
+6. **Consistency**: Maintain consistent style and format
+7. **Cross-Reference**: Link related documents
+8. **Examples**: Include code examples and diagrams
+9. **Updates**: Keep documentation up-to-date
+10. **Quality**: Review and improve documentation regularly
+
+## Agent Instructions
+
+When working as the Research Agent:
+
+1. **Always check existing documentation** before creating new docs
+2. **Verify features** in the codebase, especially `AppSidebar.tsx`
+3. **Maintain language separation**: Turkish for features/goals, English for technical
+4. **Follow Cursor best practices** for documentation structure
+5. **Keep documentation accurate** and synchronized with code
+6. **Use semantic search** to understand the codebase
+7. **Document comprehensively** but concisely
+8. **Cross-reference** related documents
+9. **Update regularly** as the project evolves
+10. **Maintain quality** through review and improvement
+
+## Conclusion
+
+The Research Agent plays a crucial role in maintaining high-quality documentation for the Uygar Koleji project. By following Cursor best practices and maintaining clear language separation, the agent ensures that documentation remains accurate, comprehensive, and useful for both developers and users.
+
+---
+
+**Document Version**: 1.0  
+**Last Updated**: 2026-01-17  
+**Language**: English (as per agent documentation standards)

package/package.json

@@ -1,11 +1,16 @@
 {
   "name": "analyze-codebase",
-  "description": "Codebase Analyzer",
+  "description": "A powerful CLI tool for analyzing codebase structure, naming conventions, code quality metrics, and detecting unused i18n translation keys",
+  "homepage": "https://github.com/mtahagocer/analyze-codebase#readme",
+  "bugs": {
+    "url": "https://github.com/mtahagocer/analyze-codebase/issues"
+  },
+  "author": "Taha Gocer <gocermtg@gmail.com>",
   "repository": {
     "type": "git",
     "url": "https://github.com/mtahagocer/analyze-codebase"
   },
-  "version": "1.2.1",
+  "version": "1.3.1",
   "main": "dist/index.js",
   "license": "MIT",
   "bin": {
@@ -17,33 +22,54 @@
     "code-analysis",
     "static-analysis",
     "file-analysis",
-    "directory-analysis",
     "naming-conventions",
-    "code-structure",
-    "file-extensions",
-    "exclude-directories",
-    "js",
-    "ts",
-    "json-output",
-    "recursive",
-    "source-code",
+    "code-quality",
+    "i18n",
+    "unused-translations",
+    "translation-keys",
+    "internationalization",
+    "watch-mode",
+    "html-report",
+    "csv-export",
+    "parallel-processing",
+    "cli-tool",
     "developer-tools",
-    "code-quality"
+    "source-code",
+    "typescript",
+    "react",
+    "vue",
+    "code-metrics"
   ],
   "scripts": {
     "cli": "ts-node ./src/index.ts",
+    "dev": "ts-node-dev --respawn --transpile-only ./src/index.ts",
     "start": "node ./dist/index.js",
     "compile": "npx rimraf dist && npx tsc",
-    "publish": "npm run compile && npm publish"
-  },
-  "devDependencies": {
-    "@types/node": "^20.1.5",
-    "ts-node": "^10.9.1",
-    "typescript": "^5.0.4"
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "prepublishOnly": "npm run compile"
   },
   "dependencies": {
+    "boxen": "^5.1.2",
     "chalk": "4.1.0",
+    "chokidar": "^4.0.3",
+    "cli-progress": "^3.12.0",
     "cli-table3": "^0.6.3",
-    "commander": "^10.0.1"
+    "commander": "^10.0.1",
+    "fast-glob": "^3.3.2",
+    "inquirer": "^12.9.6",
+    "ora": "^5.4.1",
+    "simple-git": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/chokidar": "^2.1.7",
+    "@types/cli-progress": "^3.11.0",
+    "@types/inquirer": "^9.0.7",
+    "@types/node": "^20.1.5",
+    "ts-node": "^10.9.1",
+    "ts-node-dev": "^2.0.0",
+    "typescript": "^5.0.4",
+    "vitest": "^2.1.8"
   }
-}
+}

package/readme.md

@@ -1,164 +1,241 @@
+<p align="center">
+  <h1 align="center">analyze-codebase</h1>
+  <p align="center">
+    <strong>Know your codebase. Fix what's broken. Ship with confidence.</strong>
+  </p>
+  <p align="center">
+    <a href="https://www.npmjs.com/package/analyze-codebase"><img src="https://img.shields.io/npm/v/analyze-codebase.svg?style=flat-square&color=blue" alt="npm version"></a>
+    <a href="https://www.npmjs.com/package/analyze-codebase"><img src="https://img.shields.io/npm/dm/analyze-codebase.svg?style=flat-square&color=green" alt="npm downloads"></a>
+    <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square" alt="License: MIT"></a>
+    <a href="https://github.com/mtahagocer/analyze-codebase"><img src="https://img.shields.io/github/stars/mtahagocer/analyze-codebase?style=flat-square" alt="GitHub stars"></a>
+  </p>
+</p>
 
-# Codebase Analyzer
+---
 
-Codebase Analyzer is a command-line tool that analyzes a specified directory and provides summary information about the code files it contains. It can help you gain insights into your codebase's structure, naming conventions, and content types.
+A zero-config CLI that scans your entire project in seconds and gives you a clear picture of what's inside: **file structure**, **naming conventions**, **code-vs-comment ratios**, and most uniquely, **unused i18n translation keys** that bloat your bundles.
 
-![Example Image](./example-output.png)
+```bash
+npx analyze-codebase ./src
+```
 
+That's it. No config needed.
 
-## Features
+## Why analyze-codebase?
 
-- Analyzes the specified directory recursively
-- Provides summary information about file name cases and content types
-- Supports filtering by file extensions and excluding specific directories/files
-- Customizable through command-line options
+| Problem | Solution |
+|---------|----------|
+| "How consistent are our naming conventions?" | Detects 13+ naming cases (camelCase, PascalCase, kebab-case, snake_case...) |
+| "How much of our code is actually comments?" | Breaks down physical lines, source code, comments, TODOs, empty lines |
+| "We have hundreds of translation keys. Which ones are unused?" | Scans your entire codebase for unused i18n keys and safely removes them |
+| "I need a report for my team" | Export as **HTML**, **CSV**, or **JSON** with one flag |
+| "I want this running in my workflow" | Watch mode, CI/CD friendly, config file support |
 
-## Installation
-
-You can install Codebase Analyzer globally using NPM:
+## Quick Start
 
 ```bash
-npm install -g analyze-codebase 
-```
+# Install globally
+npm install -g analyze-codebase
 
-or use with npx
-
-```bash
-npx analyze-codebase ./MyProject --exclude node_modules dist --extensions .tsx .ts
+# Or run instantly with npx
+npx analyze-codebase .
 ```
 
-## Usage
-
-To analyze a directory, use the analyze command followed by the directory path. Here's an example:
+### Setup a config file (optional)
 
 ```bash
-analyze-codebase ./MyProject --exclude node_modules dist --extensions .tsx .ts
+analyze-codebase init
 ```
 
-## Options
-
-- -f, --framework <framework>: Specify the framework used in the codebase.
-- -e, --extensions <extensions...>: Specify the file extensions to include in the analysis. You can provide multiple extensions separated by spaces. Example: -e .js .ts.
+This creates `.analyze-codebase.json` in your project root with your preferred settings. After that, just run `analyze-codebase` - it auto-discovers your config.
 
-- -e, --exclude <exclude...>: Specify directories or files to exclude from the analysis. You can provide multiple paths separated by spaces. Example: -e node_modules dist.
+## Features
 
-- --checkFileNames [checkFileNames]: Check file names. Default: true.
+### 1. Codebase Structure Analysis
 
-- --checkFileContent [checkFileContent]: Check file content. Default: true.
+Recursively scans your project and provides a breakdown of:
 
-- -w or --writeJsonOutput [writeJsonOutput]: Write json putput for tracking. Default false
+- **File naming conventions** - Are your files consistently named? camelCase? PascalCase? kebab-case? You'll see the exact distribution.
+- **Code content metrics** - Physical lines, source code lines, comments, block comments, single-line comments, TODOs, empty lines.
+- **Smart defaults** - Automatically excludes `node_modules`, `dist`, `build`, `coverage`, `.git`, `.next`, `public`, `test`, `tests`, `mocks`.
 
-## Black list
+```bash
+# Analyze TypeScript files in your src directory
+analyze-codebase ./src --extensions ts tsx
 
-analyze-codebase by default have a black list of folder names which don't want to analyze which this directories mostly should be out of analyze (i.e. dist or static files)
+# Analyze with a specific framework tag
+analyze-codebase ./src -f react --extensions ts tsx js jsx
+```
 
-- node_modules
-- dist
-- build
-- coverage
-- public
-- test
-- tests
-- mocks
+> **Tip:** Extensions work with or without the dot prefix - both `ts` and `.ts` are accepted.
 
-## Examples
+### 2. Unused i18n Translation Key Detection
 
-Analyze a directory with default options:
+This is the feature that sets `analyze-codebase` apart. If you work with internationalization, you know the pain: translation files grow over time, keys get orphaned, and nobody knows which ones are still in use.
 
 ```bash
-analyze-codebase ./src
+analyze-codebase ./src --i18n-file locales/en.json
 ```
 
-Analyze a directory with a specified framework and file extensions:
+**What it does:**
 
-```bash
-analyze-codebase ./src -f react --extensions .js .jsx .ts .tsx
-```
+1. Parses your translation JSON (supports deeply nested structures)
+2. Flattens all keys to dot-notation paths (e.g., `common.buttons.submit`)
+3. Scans every source file in your project for usage
+4. Shows you exactly which keys are unused
+5. Asks for confirmation, then safely removes them
 
-Exclude specific directories from the analysis:
+**Supported patterns** - it understands how real apps use translations:
 
-```bash
-analyze-codebase ./src --exclude node_modules dist
+```js
+// All of these are detected:
+t('key')                    // react-i18next, i18next
+t("key")                    // double quotes
+t(`key`)                    // template literals
+i18n.t('key')               // direct i18n object access
+$t('key')                   // Vue i18n
+translate('key')            // custom translate functions
+
+// Even dynamic keys:
+t(`namespace.${variable}`)  // template literal interpolation
+t('namespace.' + variable)  // string concatenation
 ```
 
-Analyze only file names
+When dynamic keys are detected, all child keys under that namespace are automatically marked as used - preventing false positives.
 
-```bash
-analyze-codebase ./src --exclude node_modules dist --checkFileContent=false
-```
+### 3. Export Reports
 
-Analyze only file content
+Generate shareable reports in three formats:
 
 ```bash
-analyze-codebase ./src --exclude node_modules dist --checkFileNames=false
-```
+# Beautiful styled HTML report
+analyze-codebase ./src --export html --output report.html
 
-Write json output of this analyze
+# Spreadsheet-friendly CSV
+analyze-codebase ./src --export csv --output data.csv
 
-```bash
-analyze-codebase -w
+# Structured JSON for programmatic use
+analyze-codebase ./src --export json --output results.json
 ```
-or 
+
+The HTML report includes styled tables, gradient headers, and is ready to share with your team or stakeholders.
+
+### 4. Watch Mode
+
+Automatically re-runs analysis whenever files change. Perfect for development:
 
 ```bash
-analyze-codebase --writeJsonOutput
+analyze-codebase ./src --watch
 ```
 
-## Contribution
+- 500ms debounce to prevent excessive runs
+- Graceful Ctrl+C shutdown
+- Works with all analysis options
 
-We welcome contributions to enhance the functionality and features of Codebase Analyzer. To contribute to the project, please follow these steps:
+### 5. Parallel Processing
 
-Fork the repository by clicking on the "Fork" button at the top right corner of this page.
+Files are processed in parallel with auto-optimized concurrency:
 
-Clone the forked repository to your local machine:
+| Project Size | Default Concurrency |
+|-------------|-------------------|
+| < 100 files | 20 concurrent ops |
+| 100-500 files | 25 concurrent ops |
+| 500+ files | 30 concurrent ops |
 
 ```bash
-git clone https://github.com/your-username/analyze-codebase.git
+# Override if needed
+analyze-codebase ./src --max-concurrency 50
 ```
 
-Create a new branch for your feature or bug fix:
+## All CLI Options
 
-```bash
-git checkout -b feature/your-feature-name
 ```
+Usage: analyze-codebase [directory] [options]
 
-or 
+Options:
+  -f, --framework <name>          Tag the framework (react, vue, angular...)
+  -e, --extensions <ext...>       File extensions to include (ts tsx js jsx)
+  -exc, --exclude <dirs...>       Additional directories to exclude
+  --checkFileNames [bool]         Analyze file naming conventions (default: true)
+  --checkFileContent [bool]       Analyze code content metrics (default: true)
+  -w, --writeJsonOutput [bool]    Write JSON output to track changes over time
+  --i18n-file <path>              Path to i18n JSON file for unused key detection
+  --watch                         Re-analyze automatically on file changes
+  --no-progress                   Disable progress bar (useful for CI/CD)
+  --max-concurrency <number>      Max parallel file operations (default: auto)
+  --export <format>               Export as json, csv, or html
+  --output <path>                 Output file path for export
 
+Commands:
+  init                            Create .analyze-codebase.json interactively
+```
 
-```bash
-git checkout -b bugfix/your-bug-fix
+## Config File
+
+Create `.analyze-codebase.json` in your project root (or run `analyze-codebase init`):
+
+```json
+{
+  "extensions": [".ts", ".tsx", ".js", ".jsx"],
+  "exclude": ["node_modules", "dist", "build"],
+  "checkFileNames": true,
+  "checkFileContent": true,
+  "framework": "react",
+  "showProgress": true,
+  "parallel": true
+}
 ```
 
-Make your modifications and additions to the codebase.
+The config is auto-discovered by searching up the directory tree. CLI flags always take precedence over config values.
 
-Test your changes thoroughly to ensure they do not introduce any issues.
+## Real-World Examples
 
-Commit your changes with a descriptive commit message:
+### Code Review Preparation
 
 ```bash
-git commit -m "Add your commit message here"
+# Get a full picture before a code review
+analyze-codebase ./src --extensions ts tsx --export html --output review.html
 ```
 
-Push your changes to your forked repository:
+### CI/CD Pipeline
 
 ```bash
-git push origin feature/your-feature-name
+# Silent mode for CI - just export the data
+analyze-codebase ./src --no-progress --export json --output analysis.json
 ```
-or
+
+### Translation Cleanup Sprint
 
 ```bash
-git push origin bugfix/your-bug-fix
+# Find and remove all unused translation keys
+analyze-codebase ./src --i18n-file public/locales/en.json --extensions ts tsx
 ```
 
-Open a pull request (PR) from your forked repository to the original repository. Provide a clear and concise description of your changes in the PR.
+### Monorepo Analysis
 
-Wait for the maintainers to review your PR. They may provide feedback or request additional changes.
+```bash
+# Analyze specific packages
+analyze-codebase ./packages/web --extensions ts tsx -f react
+analyze-codebase ./packages/api --extensions ts -f express
+```
 
-Once your PR is approved, it will be merged into the main branch, and your contributions will become a part of the Codebase Analyzer project.
+## Contributing
 
-Please ensure that you adhere to our code of conduct and follow the guidelines provided in the CONTRIBUTING.md file for a smooth and collaborative contribution process.
+Contributions are welcome! Here's how:
 
-Thank you for your interest in improving Codebase Analyzer! Your contributions are highly appreciated.
+1. Fork the repository
+2. Create your branch: `git checkout -b feature/amazing-feature`
+3. Make your changes and test them: `npm test`
+4. Commit: `git commit -m "feat: add amazing feature"`
+5. Push: `git push origin feature/amazing-feature`
+6. Open a Pull Request
 
 ## License
-This project is licensed under the MIT License.
+
+MIT - see [LICENSE](./LICENSE) for details.
+
+---
+
+<p align="center">
+  <sub>Built by <a href="https://github.com/mtahagocer">Taha Gocer</a></sub>
+</p>