Technical Documentation

Comprehensive technical documentation for developers, including architecture details, API reference, and development guidelines.

Architecture Overview

File Insights follows a modern, enterprise-grade architecture with clear separation of concerns.

Extension Layer

extension.ts

Entry point - minimal, delegates to ExtensionManager

Manager Layer

ExtensionManager

Main coordinator, handles lifecycle and events

StatusBarManager

Status bar UI management

Service Layer

ConfigurationService

VS Code settings integration

FileService

File system operations

Utility Layer

Formatter

Size formatting logic

Logger

Structured logging

Component Details

Detailed documentation for each architectural component.

ExtensionManager

src/managers/extensionManager.ts

Central coordinator managing the extension lifecycle, event listener registration, and command handling with performance optimization.

Key Responsibilities:

  • Extension activation and deactivation
  • Event listener registration and cleanup
  • Command registration and handling
  • Performance optimization with debounced updates
  • Integration with other managers and services

Public Methods:

activate(context: ExtensionContext): void

Initializes the extension and registers all components

deactivate(): void

Cleans up resources and disposes of all components

refresh(): void

Manually refreshes file size information

StatusBarManager

src/managers/statusBarManager.ts

Dedicated status bar item management with configuration-aware positioning, tooltip generation, and error state handling.

Key Responsibilities:

  • Status bar item creation and management
  • Dynamic positioning based on configuration
  • Tooltip generation with detailed information
  • Icon and text display management
  • Error state visualization

Public Methods:

updateDisplay(fileSize: number, filePath: string): void

Updates the status bar with current file information

show(): void

Shows the status bar item

hide(): void

Hides the status bar item

dispose(): void

Disposes of the status bar item

ConfigurationService

src/services/configurationService.ts

VS Code settings integration with real-time configuration updates, type-safe access, and change notification system.

Key Responsibilities:

  • VS Code settings integration
  • Real-time configuration updates
  • Type-safe configuration access
  • Configuration change notifications
  • Default value management

Configuration Properties:

enabled: boolean

Extension enable/disable state

displayFormat: DisplayFormat

Size display format (auto, bytes, kb, mb)

statusBarPosition: StatusBarPosition

Status bar positioning (left, right)

showTooltip: boolean

Tooltip display control

refreshInterval: number

Update frequency in milliseconds

maxFileSize: number

Maximum analyzable file size

FileService

src/services/fileService.ts

File system operations with comprehensive error handling, file validation, and async processing capabilities.

Key Responsibilities:

  • File system operations with error handling
  • File validation (scheme, type, existence)
  • Async file stats retrieval
  • Size limit enforcement
  • Path normalization and validation

Public Methods:

getFileSize(filePath: string): Promise<number | null>

Retrieves file size with error handling

isValidFile(uri: vscode.Uri): boolean

Validates file URI and scheme

getFileStats(filePath: string): Promise<FileStats | null>

Gets comprehensive file statistics

API Reference

Complete API documentation for types, interfaces, and enums.

Types & Interfaces

ExtensionConfig

interface ExtensionConfig {
  enabled: boolean;
  displayFormat: DisplayFormat;
  statusBarPosition: StatusBarPosition;
  showTooltip: boolean;
  refreshInterval: number;
  maxFileSize: number;
}

Main configuration interface for the extension

FileStats

interface FileStats {
  size: number;
  path: string;
  lastModified: Date;
  isFile: boolean;
  isDirectory: boolean;
}

File statistics information

LogLevel

enum LogLevel {
  ERROR = 'error',
  WARN = 'warn',
  INFO = 'info',
  DEBUG = 'debug'
}

Logging levels for structured logging

DisplayFormat

enum DisplayFormat {
  AUTO = 'auto',
  BYTES = 'bytes',
  KB = 'kb',
  MB = 'mb'
}

File size display format options

StatusBarPosition

enum StatusBarPosition {
  LEFT = 'left',
  RIGHT = 'right'
}

Status bar positioning options

Commands

fileInsights.enable

Enables the File Insights extension

Category: File Insights

Title: File Insights: Enable

fileInsights.disable

Disables the File Insights extension

Category: File Insights

Title: File Insights: Disable

fileInsights.refresh

Manually refreshes file size information

Category: File Insights

Title: File Insights: Refresh

fileInsights.showDetails

Shows detailed file information dialog

Category: File Insights

Title: File Insights: Show Details

fileInsights.showOutputChannel

Opens the debug output channel

Category: File Insights

Title: File Insights: Show Output Channel

Development Guide

Guidelines for contributing to and extending File Insights.

Setup Development Environment

1. Clone Repository

git clone https://github.com/Vijay431/file-insights.git
cd file-insights

2. Install Dependencies

npm install

3. Build Extension

npm run compile

4. Run Tests

npm test

Available Commands

Command Description Usage
npm run compile Compile TypeScript files using webpack Development builds
npm run watch Watch mode for development Auto-recompilation
npm run package Build production bundle Production builds
npm test Run VS Code extension tests Testing
npm run lint Run ESLint on source files Code quality
npm run format Format code using Prettier Code formatting

Code Standards

TypeScript

  • Strict mode enabled
  • ES2022 target
  • No any types
  • Comprehensive type definitions

Code Quality

  • ESLint with TypeScript rules
  • Prettier formatting
  • Comprehensive error handling
  • Structured logging

Architecture

  • Separation of concerns
  • Manager/Service pattern
  • Dependency injection
  • Resource disposal

Testing

  • @vscode/test-electron
  • Real VS Code API testing
  • Comprehensive coverage
  • TDD approach

Performance Considerations

Key performance optimizations and best practices implemented in File Insights.

Debounced Updates

Intelligent debouncing prevents excessive file system calls during rapid file changes, with configurable intervals (100-5000ms).

Memory Management

Proper resource disposal, event listener cleanup, and memory leak prevention ensure minimal memory footprint.

Optimized Bundle

Webpack bundling with tree-shaking, compression, and minimal dependencies result in a small extension size.

File Filtering

Configurable file size limits and scheme validation prevent processing of unsupported or overly large files.

Contributing

Help improve File Insights by contributing code, documentation, or feedback.

Code Contributions

Submit bug fixes, new features, or performance improvements via pull requests.

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. Submit a pull request

Bug Reports

Report bugs or issues to help improve the extension's reliability.

  1. Check existing issues
  2. Create detailed bug report
  3. Include system information
  4. Provide reproduction steps
  5. Add relevant screenshots

Documentation

Improve documentation, add examples, or suggest clarifications.

  1. Identify documentation gaps
  2. Create improvement proposal
  3. Write clear documentation
  4. Add practical examples
  5. Submit pull request
Report Issue Submit PR Join Discussion