Explain This Project

A powerful VS Code extension that analyzes your project structure and generates a comprehensive PROJECT_OVERVIEW.md file with details about languages, frameworks, dependencies, and architecture.

This is not a coding agent. It does not modify source code, scaffold new projects, or assume intent. It reads what exists and reports it accurately.

Features

Multi-Language Support

• JavaScript/TypeScript - Analyzes package.json, detects frameworks (React, Vue, Svelte, Next.js, Express, etc.)
• Python - Supports requirements.txt and pyproject.toml, detects Django/Flask frameworks
• Rust - Parses Cargo.toml, identifies applications vs libraries
• Go - Analyzes go.mod files and project structure
• PHP - Reads composer.json, detects Laravel, Symfony, CakePHP
• Java, C#, C++, C - Basic file extension detection
• And more...

Smart Project Analysis

• Project Name & Type detection from configuration files
• Framework Detection from declared dependencies (no guesswork)
• Entry Points identification based on language conventions
• Dependency Analysis from package managers
• Directory Structure overview (ignores noise like node_modules)

Clean Output

• Generates a well-formatted PROJECT_OVERVIEW.md file
• Structured sections for easy reading
• Timestamps for tracking when analysis was performed
• No hallucination - only reports what actually exists

� Installation

From VS Code Marketplace

1. Open VS Code
2. Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
3. Search for "Explain This Project"
4. Click Install

From VSIX File

# Download the .vsix file, then:
code --install-extension explain-this-project-0.1.0.vsix

Usage

1. Open a project folder in VS Code
2. Open Command Palette (Cmd+Shift+P / Ctrl+Shift+P)
3. Run command: Explain This Project
4. View results: The extension creates PROJECT_OVERVIEW.md in your project root

Example Output

# Project Overview

## Basic Information

**Name:** my-react-app
**Type:** Application (Build-enabled)
**Primary Language:** TypeScript

## Frameworks & Libraries

- React
- Express

## Entry Points

- `src/index.ts`
- `src/server.ts`

## Project Structure

- `src/`
- `public/`
- `tests/`

## Dependencies

- react
- react-dom
- express

## Development Dependencies

- typescript
- eslint
- @types/react

---
*Generated by Explain This Project extension on 2025-11-07T18:30:00.000Z*

Configuration

The extension can be customized through VS Code settings:

{
  "explainThisProject.includeDevDependencies": true,
  "explainThisProject.maxDirectoryDepth": 3,
  "explainThisProject.excludeDirectories": [
    "node_modules", ".git", "dist", "build", "coverage"
  ]
}

Available Settings

📋 Requirements

• VS Code 1.105.0 or higher
• An open workspace/folder (the extension analyzes the current workspace)
• No network connectivity required
• No external dependencies needed

🛠️ Development

Prerequisites

# Install VS Code Extension CLI
npm install -g @vscode/vsce

Building the Extension

# Install dependencies
npm install

# Compile TypeScript
npm run compile

# Watch for changes during development
npm run watch

# Run tests
npm test

# Lint code
npm run lint

# Package for distribution
vsce package

Testing the Extension

# Run unit tests
npm test

# Package and install locally
vsce package
code --install-extension explain-this-project-0.1.0.vsix

# Test in Extension Development Host
# Press F5 in VS Code to launch a new Extension Development Host window

Project Structure

├── src/
│   ├── extension.ts          # Main extension entry point
│   ├── types.ts             # TypeScript interfaces
│   └── runner/
│       ├── projectAnalysis.ts    # Core analysis logic
│       ├── renderMarkdown.ts     # Markdown generation
│       └── fileSystem.ts         # File utilities
├── package.json             # Extension metadata
└── tsconfig.json           # TypeScript configuration

Roadmap

• VS Code Sidebar View - Interactive project overview panel
• CLI Version - Standalone command-line tool
• AI Integration - Optional natural language summaries
• Configuration Files Analysis - Deeper insights into project setup
• Architecture Visualization - Dependency graphs and structure diagrams

Publishing

To VS Code Marketplace

# First time setup
vsce login <your-publisher-name>

# Publish
vsce publish

# Or publish with version bump
vsce publish patch  # 0.1.0 -> 0.1.1
vsce publish minor  # 0.1.0 -> 0.2.0
vsce publish major  # 0.1.0 -> 1.0.0

Package for Distribution

# Create .vsix file
vsce package

# Share the .vsix file for manual installation
# Others can install with: code --install-extension explain-this-project-0.1.0.vsix

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes and add tests
4. Run tests: npm test
5. Ensure linting passes: npm run lint
6. Commit your changes: git commit -am 'Add some feature'
7. Push to the branch: git push origin feature-name
8. Submit a pull request

Development Guidelines

• Follow TypeScript best practices
• Add tests for new features
• Update documentation as needed
• Ensure all ESLint rules pass
• Test with multiple project types

Troubleshooting

Common Issues

Extension doesn't appear in Command Palette

• Ensure you have a workspace/folder open in VS Code
• Restart VS Code after installation

No PROJECT_OVERVIEW.md generated

• Check VS Code Output panel for error messages
• Ensure you have read permissions in the project directory
• Try running on a simpler project first

Incomplete analysis

• Check if configuration files (package.json, etc.) are valid JSON/TOML
• Verify the project structure matches expected patterns
• Review excluded directories in settings

Performance issues with large projects

• Reduce maxDirectoryDepth in settings
• Add large directories to excludeDirectories
• Consider analyzing subdirectories separately

Getting Help

1. Check the Issues page for similar problems
2. Enable VS Code Developer Tools (Help > Toggle Developer Tools) to see console errors
3. Create a minimal reproduction case
4. Open a new issue with:
   • VS Code version
   • Extension version
   • Project type and structure
   • Error messages or logs

License

This project is licensed under the MIT License - see the LICENSE file for details.

Issues & Support

Found a bug or have a feature request? Please open an issue on GitHub.

Support This Project

• Star this repository if you find it helpful
• Report bugs and suggest features
• Share with other developers
• Contribute code or documentation improvements