From 5908c010ef84ff9e13facecb9905cb0914fdf338 Mon Sep 17 00:00:00 2001 From: Kiro Agent <244629292+kiro-agent@users.noreply.github.com> Date: Thu, 4 Dec 2025 21:29:36 +0000 Subject: [PATCH] Add comprehensive repository summary documentation in README2.md Co-authored-by: siakmun-aws <189797307+siakmun-aws@users.noreply.github.com> --- README2.md | 491 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 491 insertions(+) create mode 100644 README2.md diff --git a/README2.md b/README2.md new file mode 100644 index 00000000000..5e50fb0c14b --- /dev/null +++ b/README2.md @@ -0,0 +1,491 @@ +# AWS Toolkit for Visual Studio Code - Comprehensive Repository Summary + +## Project Overview and Purpose + +The AWS Toolkit for Visual Studio Code is a comprehensive monorepo that houses multiple Visual Studio Code extensions designed to enhance the development experience for AWS services and AI-powered coding assistance. The repository contains two main extensions: + +### 1. **AWS Toolkit for Visual Studio Code** +A full-featured extension that enables developers to interact with AWS services directly from their IDE. It provides seamless integration with various AWS services, making it easier to develop, debug, and deploy cloud applications. + +### 2. **Amazon Q for Visual Studio Code** +An AI-powered assistant extension leveraging generative AI to accelerate software development through code suggestions, explanations, security analysis, and application upgrades. + +**Repository**: https://github.com/aws/aws-toolkit-vscode +**License**: Apache License 2.0 +**Publisher**: Amazon Web Services + +--- + +## Main Features and Capabilities + +### AWS Toolkit Features +- **AWS Authentication & Connectivity** + - Connect with IAM credentials, IAM Identity Center (SSO), or AWS Builder ID + - Support for multiple authentication mechanisms + +- **Development Environment Integration** + - Connect VS Code to EC2 instances + - Integration with CodeCatalyst Dev Environments + - Open terminal sessions on EC2 instances or ECS tasks + +- **Serverless Application Development** + - Debug Lambda functions using SAM CLI + - SAM/CloudFormation template validation and autocomplete + - Infrastructure as Code (IaC) support + +- **AWS Service Explorer** + - Browse and interact with AWS resources + - S3 file system support + - CloudWatch Logs search and viewing + - Support for multiple AWS services (Lambda, API Gateway, AppRunner, CloudFormation, etc.) + +- **Application Composer** + - Visual design and composition of cloud applications + +### Amazon Q Features +- **AI-Powered Code Assistance** + - Inline code suggestions as you type + - Context-aware code generation + +- **Interactive Chat** + - Generate code through natural language conversations + - Get explanations for existing code + - Ask questions about software development + +- **Security Analysis** + - Analyze and fix security vulnerabilities in projects + - Automated security scanning + +- **Application Transformation** + - Upgrade Java applications automatically + - Modernization assistance + +--- + +## Technology Stack and Architecture + +### Core Technologies + +#### Programming Languages & Runtimes +- **TypeScript** (Primary language, version 5.0.4+) +- **Node.js** (v22.7.5+, NPM v10.1.0+) +- **Target**: ES2021 with Node16 module system + +#### Build & Development Tools +- **Webpack** (v5.95.0) - Module bundling and optimization +- **ts-node** (v10.9.1) - TypeScript execution +- **ESLint** (v8.56.0) - Code linting with custom plugins +- **Prettier** (v3.3.3) - Code formatting +- **Husky** (v9.0.7) - Git hooks + +#### Testing Frameworks +- **c8** - Code coverage +- **@vscode/test-electron** (v2.3.8) - Desktop extension testing +- **@vscode/test-web** (v0.0.65) - Web mode testing +- **@playwright/browser-chromium** (v1.43.1) - E2E testing + +#### VS Code Integration +- **VS Code API** (v1.68.0+) +- **VS Code Extension Minimum Version**: 1.83.0 +- **Extension Kinds**: Workspace extensions (both desktop and web modes) + +#### AWS SDK & Services +The toolkit integrates with numerous AWS services through the AWS SDK v3: +- **Core Services**: Lambda, S3, EC2, IAM, SSM, CloudFormation +- **Data Services**: DynamoDB, DocumentDB, CloudWatch Logs +- **Developer Services**: CodeCatalyst, API Gateway, AppRunner +- **AI Services**: Amazon Q Developer streaming clients +- **SDK Version**: <3.731.0 (various @aws-sdk/* packages) + +#### Additional Libraries +- **AWS SDK v2** (v2.1692.0) - Legacy support +- **@aws/mynah-ui** (v4.30.1) - Chat UI components +- **amazon-states-language-service** (v1.16.1) - Step Functions support +- **aws-ssm-document-language-service** (v1.0.0) - SSM document support +- **@zip.js/zip.js** (v2.7.41) - Archive handling +- **diff** (v5.1.0) - File comparison +- **glob** (v10.3.10) - Pattern matching +- **vscode-nls** (v5.2.0) - Internationalization + +### Architecture Pattern + +#### Monorepo Structure +The project follows a **TypeScript monorepo** architecture using **NPM workspaces**: + +``` +aws-toolkit-vscode/ +├── packages/ +│ ├── core/ # Shared functionality and utilities +│ ├── toolkit/ # AWS Toolkit extension +│ └── amazonq/ # Amazon Q extension +├── plugins/ +│ └── eslint-plugin-aws-toolkits/ # Custom linting rules +├── src.gen/ # Generated source code +└── scripts/ # Build and automation scripts +``` + +#### Design Principles + +1. **Environment Abstraction** + - Code organized into `node/`, `web/`, and common modules + - Supports both desktop (Node.js) and web (browser) environments + - Clear separation between environment-specific and common code + +2. **Command Pattern** + - Centralized command handling through `Commands` abstraction + - Consistent logging, error handling, and telemetry + - Support for CodeLens, TreeView, and direct command execution + +3. **Shared Core Library** + - `packages/core/` contains reusable functionality + - Shared authentication, utilities, and AWS service integrations + - Extension-specific code in toolkit/amazonq packages + +4. **Modular Feature Organization** + - Features organized by AWS service or functionality + - Clear separation of concerns + - Independent test suites per package + +--- + +## Key Directories and Project Structure + +### Root Level Structure + +``` +/ +├── .changes/ # Release changelog fragments +├── .github/ # GitHub workflows and templates +├── .husky/ # Git hooks configuration +├── .vscode/ # VS Code workspace settings +├── buildspec/ # AWS CodeBuild specifications +├── designs/ # Architecture and design documents +├── docs/ # Comprehensive documentation +├── packages/ # Main source packages (monorepo) +├── plugins/ # Custom ESLint plugins +├── scripts/ # Build and utility scripts +├── src.gen/ # Generated/vendor code +├── Dockerfile # Docker configuration for CI/CD +├── package.json # Root workspace configuration +├── tsconfig.json # Root TypeScript configuration +└── aws-toolkit-vscode.code-workspace # VS Code workspace file +``` + +### Packages Structure + +#### `packages/core/` - Core Library +**Purpose**: Shared functionality and business logic + +``` +packages/core/src/ +├── amazonq/ # Amazon Q core features +├── amazonqDoc/ # Q documentation features +├── amazonqFeatureDev/ # Q feature development +├── amazonqGumby/ # Q transformation (Java upgrades) +├── amazonqScan/ # Q security scanning +├── amazonqTest/ # Q test generation +├── applicationcomposer/ # Visual app composition +├── auth/ # Authentication & credentials +├── awsService/ # AWS service integrations +├── awsexplorer/ # AWS resource explorer +├── codecatalyst/ # CodeCatalyst integration +├── codewhisperer/ # CodeWhisperer (AI code) +├── codewhispererChat/ # AI chat functionality +├── dev/ # Developer utilities +├── docdb/ # DocumentDB support +├── dynamicResources/ # Dynamic AWS resources +├── eventSchemas/ # EventBridge schemas +├── feedback/ # User feedback mechanisms +├── lambda/ # Lambda development & debugging +├── login/ # Login workflows +├── notifications/ # User notifications +├── shared/ # Common utilities +│ ├── node/ # Node.js-specific code +│ ├── web/ # Browser-specific code +│ └── [various modules] # General utilities +├── ssmDocument/ # SSM document support +├── stepFunctions/ # Step Functions integration +├── testE2E/ # End-to-end tests +├── testInteg/ # Integration tests +├── testFixtures/ # Test data and fixtures +├── threatComposer/ # Threat modeling +├── web/ # Web-specific entry point +├── webviews/ # UI components +├── extension.ts # Extension activation logic +├── extensionNode.ts # Node.js entry point +└── extensionWeb.ts # Web entry point +``` + +#### `packages/toolkit/` - AWS Toolkit Extension +**Purpose**: AWS Toolkit-specific implementation and packaging + +``` +packages/toolkit/ +├── src/ # Toolkit-specific source code +├── test/ # Toolkit-specific tests +├── scripts/ # Build scripts +├── package.json # Extension manifest +├── webpack.config.js # Webpack configuration +└── README.md # Extension documentation +``` + +#### `packages/amazonq/` - Amazon Q Extension +**Purpose**: Amazon Q-specific implementation and packaging + +``` +packages/amazonq/ +├── src/ # Q-specific source code +├── test/ # Q-specific tests +├── scripts/ # Build scripts +├── package.json # Extension manifest +├── webpack.config.js # Webpack configuration +└── README.md # Extension documentation +``` + +### Important Configuration Files + +- **`package.json`** (root): Workspace configuration, scripts, and shared dependencies +- **`tsconfig.json`**: Root TypeScript configuration for scripts +- **`packages/tsconfig.packages.json`**: Base TypeScript config for all packages +- **`.eslintrc.js`**: Linting rules and configuration +- **`webpack.base.config.js`**: Shared webpack configuration +- **`aws-toolkit-vscode.code-workspace`**: Multi-root workspace configuration + +### Scripts Directory + +``` +scripts/ +├── clean.ts # Cleanup build artifacts +├── createRelease.ts # Release management +├── generateIcons.ts # Icon generation from codicons +├── generateNonCodeFiles.ts # Generate metadata files +├── generateSettings.ts # Generate settings schema +├── mergeReports.ts # Merge test coverage reports +├── newChange.ts # Create changelog entries +├── package.ts # Package VSIX files +├── prepare.ts # Pre-build preparation +└── skippedTestReport.ts # Analyze skipped tests +``` + +### Documentation Directory + +``` +docs/ +├── ARCHITECTURE.md # Architecture overview +├── CODE_GUIDELINES.md # Coding standards +├── TESTPLAN.md # Testing strategy +├── arch_develop.md # Development view +├── arch_features.md # Feature view +├── arch_overview.md # Overall architecture +├── arch_runtime.md # Runtime behavior +├── arch_target.md # Deployment targets +├── arch_user_stories.md # User scenarios +├── build.md # Build documentation +├── connecting-to-aws.md # AWS connection guide +├── faq-credentials.md # Credential troubleshooting +└── [various other docs] # Additional documentation +``` + +--- + +## Development Setup Information + +### Prerequisites + +1. **Required Software** + - [Visual Studio Code](https://code.visualstudio.com/Download) (latest version) + - [Node.js and NPM](https://nodejs.org/) (Node v22+, NPM v10.1.0+) + - [TypeScript](https://www.typescriptlang.org/) (v5.0.4+) + - [Git](https://git-scm.com/downloads) + - [TypeScript + Webpack Problem Matcher](https://marketplace.visualstudio.com/items?itemName=amodio.tsl-problem-matcher) (VS Code extension) + +2. **Optional but Recommended** + - [AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html) (for Lambda debugging) + - [Docker](https://docs.docker.com/get-docker/) (for containerized builds) + - [AWS `git-secrets`](https://github.com/awslabs/git-secrets) (prevent credential commits) + +### Initial Setup + +```bash +# Clone the repository +git clone git@github.com:aws/aws-toolkit-vscode.git +cd aws-toolkit-vscode + +# Optional: Configure git blame to ignore noise commits +git config blame.ignoreRevsFile .git-blame-ignore-revs + +# Install dependencies (this will trigger prepare and postinstall scripts) +npm install +``` + +### Opening the Project + +**IMPORTANT**: Due to the monorepo structure, you must open the project using the workspace file: + +1. Launch VS Code +2. Run command: `File: Open Workspace from File...` +3. Select: `aws-toolkit-vscode.code-workspace` + +### Building the Project + +#### Development Build +```bash +# Build all packages once +npm run compile + +# Build and watch for changes +npm run watch + +# Build specific package +npm run compile -w packages/toolkit +``` + +#### Production Build +```bash +# Build VSIX packages for distribution +npm run package + +# Build debug VSIX (faster, no minification) +npm run package -- --debug +``` + +**Note**: On Linux, you may need to increase Node heap size: +```bash +export NODE_OPTIONS=--max-old-space-size=8192 +``` + +### Running the Extension + +#### Desktop Mode (Node.js) +1. Open the Run panel (sidebar) +2. Select `Extension` from the dropdown +3. Press `F5` to launch a new VS Code instance with the extension + +#### Web Mode (Browser/PWA) +1. Open the Run panel (sidebar) +2. Select `Extension (web)` from the dropdown +3. Press `F5` to launch VS Code in web mode + +### Testing + +```bash +# Run all tests for all packages +npm run test + +# Run tests for specific package +npm run test -w packages/toolkit + +# Run end-to-end tests +npm run testE2E + +# Run integration tests +npm run testInteg + +# Run web tests +npm run testWeb +``` + +### Code Quality + +```bash +# Run linters +npm run lint + +# Auto-fix linting issues +npm run lintfix + +# Format code (Prettier runs via git hooks automatically) +pretty-quick +``` + +### Common Development Tasks + +#### Creating a New Change +```bash +# Create a changelog entry for a package +npm run newChange -w packages/toolkit +``` + +#### Creating a Release +```bash +# Prepare a release for a package +npm run createRelease -w packages/toolkit +``` + +#### Cleaning Build Artifacts +```bash +# Clean all build artifacts +npm run clean + +# Full reset (removes node_modules) +npm run reset +``` + +### Workspace Scripts + +The root `package.json` provides shortcuts to common operations: + +- `npm run compile` - Build all packages +- `npm run test` - Run tests in all packages +- `npm run package` - Package both extensions +- `npm run lint` - Lint all packages +- `npm run clean` - Clean build artifacts +- `npm run reset` - Full clean and reinstall + +### Project Configuration + +#### Prettier Configuration +- Print width: 120 characters +- Single quotes preferred +- No semicolons +- ES5 trailing commas +- 4-space indentation +- LF line endings + +#### TypeScript Configuration +- Module: Node16 +- Target: ES2021 +- Strict mode enabled +- No unused locals allowed +- Incremental compilation +- Source maps for debugging + +### Troubleshooting + +1. **Build Errors**: Ensure all dependencies are installed with `npm install` +2. **TypeScript Errors**: Check that workspace is opened via `.code-workspace` file +3. **Test Failures**: Run `npm run testCompile` before running tests +4. **Memory Issues**: Increase Node heap size with `NODE_OPTIONS` +5. **Git Secrets**: Install git-secrets to prevent accidental credential commits + +### Additional Resources + +- **User Guide**: https://docs.aws.amazon.com/console/toolkit-for-vscode/welcome +- **Contributing Guide**: [CONTRIBUTING.md](./CONTRIBUTING.md) +- **Architecture Docs**: [docs/arch_overview.md](./docs/arch_overview.md) +- **Code Guidelines**: [docs/CODE_GUIDELINES.md](./docs/CODE_GUIDELINES.md) +- **VS Code API**: https://code.visualstudio.com/api/references/vscode-api +- **AWS SDKs**: https://docs.aws.amazon.com/sdkref/latest/guide/overview.html + +### Support and Feedback + +- **Issues**: https://github.com/aws/aws-toolkit-vscode/issues +- **Discussions**: GitHub Discussions on the repository +- **Feature Requests**: Use the issue templates provided +- **Pull Requests**: See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines + +--- + +## Project Statistics + +- **Total Packages**: 3 main packages (core, toolkit, amazonq) + plugins +- **Primary Language**: TypeScript +- **Code Coverage**: Tracked via codecov.io +- **Testing Strategy**: Unit, Integration, E2E, and Web tests +- **CI/CD**: AWS CodeBuild integration +- **Release Management**: Automated via GitHub workflows +- **Documentation**: Comprehensive docs in `docs/` directory (>40 files) + +--- + +*This summary was generated from the repository analysis as of December 2024. For the most up-to-date information, please refer to the official repository documentation.*