Add standardized CLAUDE.md documentation for ast-cli-javascript-wrapper-runtime-cli (AST-146806)

[cx-rahul-pidde]

Summary

Create standardized CLAUDE.md file for the ast-cli-javascript-wrapper-runtime-cli repository following the Cloud MD file standardization template defined in epic AST-146793.

This comprehensive development guide includes all essential sections and recommended sections to improve understanding and consistency in deployment and maintenance.

Overview

The CLAUDE.md file serves as the central source of truth for developers working on this project, providing complete documentation of:

• Essential Sections: Project Overview, Architecture, Repository Structure, Technology Stack, Development Setup, Coding Standards, Project Rules, Testing Strategy, Known Issues
• Recommended Sections: Deployment Information, External Integrations, Performance Considerations, API/Endpoints/Interfaces, Security & Access, Logging, Debugging Steps

Key Features

✅ Project Overview - Purpose, status, and key functionality of the AST CLI JavaScript wrapper
✅ Architecture - System design with module diagram and design patterns (Multiton, Semaphore, Configuration)
✅ Repository Structure - Complete folder organization documenting 15+ feature modules
✅ Technology Stack - All dependencies, versions, and build tools (TypeScript, Jest, ESLint, Node.js, etc.)
✅ Development Setup - Step-by-step installation and configuration for Windows and Linux
✅ Coding Standards - TypeScript strict mode, naming conventions, code style, documentation guidelines
✅ Project Rules - Critical constraints, must-have checks before PRs, Git workflow
✅ Testing Strategy - Jest configuration, coverage thresholds (80% lines/functions, 60% branches), best practices
✅ Known Issues - Current limitations and documented workarounds
✅ Deployment Information - Package publication process and CI/CD workflows
✅ External Integrations - AST CLI binary, Azure Pipelines, GitHub Actions
✅ Performance Considerations - Optimization areas, bottlenecks, and metrics
✅ API & Endpoints - Main entry points (CxWrapper) and all feature modules documented
✅ Security & Access - Authentication methods, credential management, proxy support, RBAC, audit logging
✅ Logging - log4js configuration, log levels, best practices
✅ Debugging Steps - Common issues with solutions, debug techniques, VS Code setup

Documentation Highlights

Architecture Section

• Multiton pattern for CxWrapper instance management
• Semaphore-based thread-safe CLI execution
• Modular feature-based architecture with 15+ feature modules
• Clear separation of concerns (Config, Installer, Client, Execution)

Development Setup

• Detailed installation guide for Node.js projects
• Environment variable configuration examples for Windows PowerShell and Linux
• Integration test setup with Checkmarx AST API credentials
• NPM script documentation for build, test, lint, and development

Coding Standards

• TypeScript strict mode requirements (noImplicitAny, forceConsistentCasing, etc.)
• Class/function/constant naming conventions (PascalCase, camelCase, UPPER_SNAKE_CASE)
• Import/export best practices and file organization guidelines
• Error handling patterns with CxError
• JSDoc and inline comment best practices

Testing Strategy

• Jest configuration with ts-jest transformer
• Coverage thresholds: Lines 80%, Functions 80%, Branches 60%, Statements 80%
• Testing best practices using ts-mockito for mocking
• Async/await testing patterns
• Test data management in src/tests/data/

Security & Access

• Two authentication methods: API Key and OAuth 2.0 Client Credentials
• Credential management best practices (no hardcoding, use env vars)
• HTTP proxy configuration support with authentication
• HTTPS and certificate validation requirements
• Role-based access control (RBAC) enforced by AST API
• Audit and logging considerations

Debugging Guide

• Enable debug logging with log4js configuration
• Common issues and solutions:
  • AST CLI not found - troubleshooting binary installation
  • Proxy connection failures - proxy URL validation
  • Authentication failures - credential verification
  • Semaphore timeouts - concurrent execution handling
  • Type errors - TypeScript strict mode compliance
• Debug techniques: Node debugger, environment inspection, CLI testing
• VS Code debugging configuration with launch.json

Changes Made

• New File: CLAUDE.md (922 lines)
  • Comprehensive development guide covering all standardization requirements
  • Clear, well-organized sections with code examples
  • Practical debugging and troubleshooting information
  • Links to related projects and resources

Acceptance Criteria

• CLAUDE.md file created at repository root
• All 9 essential sections completed with relevant content
• All 7 recommended sections completed with relevant content
• Documentation is clear, comprehensive, and follows the standardization template
• File covers the complete project scope including architecture, setup, standards, testing, and debugging
• Ready for review and merge to main branch

Related Issues

• Epic: AST-146793 (Standardization of Claude Code Documentation)
• Story: AST-146806 (Create Claude MD file for ast-cli-javascript-wrapper-runtime-cli repository)

Testing

Documentation has been reviewed for:

• Accuracy of technical information
• Completeness of all required sections
• Clarity and usability for developers
• Consistency with project structure and practices
• Proper formatting and markdown syntax

---

🤖 Generated with Claude Code

[github-actions]

Checkmarx One – Scan Summary & Details – 57633e56-64bc-4496-abd8-44a159ed99b0

Great job! No new security vulnerabilities introduced in this pull request