squirrelVsis/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Squirrel NUT Explorer is a VS Code extension for browsing and editing NUT (Squirrel script) files through the pvfUtility API. The extension provides comprehensive language support features including code completion, hover information, definition jumping, function signature help, code formatting, and error detection.

Build Commands

# Install dependencies
npm install

# Compile TypeScript
npm run compile

# Watch mode compilation
npm run watch

# Build project
npm run build

# VS Code pre-publish build
npm run vscode:prepublish

High-Level Architecture

Core Components

1. Extension Entry Point (src/extension.ts):

   • Registers all providers and commands
   • Initializes core services and manages extension lifecycle

2. Data Model (src/model.ts):

   • FileModel class manages file state, content, and API communication
   • Handles connection to pvfUtility API and file operations
   • Manages file list and content caching

3. Tree View Provider (src/provider.ts):

   • Implements vscode.TreeDataProvider for displaying files in the explorer view
   • Manages UI representation of files and folders

4. File System Provider (src/fileSystemProvider.ts):

   • Implements vscode.FileSystemProvider for virtual file handling
   • Bridges VS Code file operations with pvfUtility API

Language Feature Providers (src/providers/)

1. Completion Provider (src/providers/completionProvider.ts):

   • Provides code completion for functions, keywords, constants, and variables
   • Includes both basic completion and dot notation completion for object methods

2. Hover Provider (src/providers/hoverProvider.ts):

   • Shows detailed information when hovering over code elements
   • Displays function signatures, descriptions, and parameter details

3. Definition Provider (src/providers/definitionProvider.ts):

   • Enables "Go to Definition" functionality for cross-file function references

4. Signature Help Provider (src/providers/signatureHelpProvider.ts):

   • Shows function parameter information during typing

5. Formatting Providers (src/providers/onTypeFormattingProvider.ts, src/providers/documentFormattingProvider.ts):

   • Handle code formatting on type and document formatting

6. Code Error Provider (src/providers/codeErrorProvider.ts):

   • Implements code diagnostics and quick fixes

Core Functionality Modules

1. Function Extractor (src/functionExtractor.ts):

   • Parses NUT files to extract function definitions
   • Manages function caching for performance
   • Provides cross-file function reference capabilities

2. API Client (src/apiClient.ts):

   • Handles all HTTP communication with pvfUtility API
   • Manages file listing, content retrieval, and file saving

3. API Parser (src/providers/apiParser.ts):

   • Provides built-in Squirrel language documentation
   • Manages API functions, classes, and constants information

Key Dependencies

• VS Code API: Foundation for extension development
• TypeScript: Development language
• Node.js HTTP/HTTPS modules: For API communication (no external HTTP libraries)

Configuration Options

The extension provides these configuration options:

• squirrel.api.baseUrl: pvfUtility API base URL (default: http://localhost)
• squirrel.api.port: pvfUtility API port (default: 8080)
• squirrel.defaultDirectory: Default directory to browse (default: sqr)
• squirrel.nutEncoding: NUT file encoding type (default: UTF8)

Development Notes

1. Caching Mechanism: FunctionExtractor uses caching to improve performance. File caches are updated when files are saved.

2. Batch Processing: Files are processed in batches to prevent memory overflow and blocking.

3. Error Handling: All API calls include exception handling to ensure extension stability.

4. Chinese Support: The project primarily uses Chinese for UI and comments, maintaining consistency in code documentation.

5. Virtual File System: The extension uses VS Code's virtual file system API to provide a seamless editing experience for remote files.

6. Performance Monitoring: Function extraction includes performance monitoring to track efficiency.