Add standardized CLAUDE.md documentation for ast-cli-javascript-wrapper-runtime-cli (AST-146806) by cx-rahul-pidde · Pull Request #202 · Checkmarx/ast-cli-javascript-wrapper-runtime-cli

cx-rahul-pidde · 2026-04-22T08:00:19Z

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

…t-wrapper-runtime-cli

- Comprehensive development guide following standardization template (AST-146793) - Includes all essential sections: Project Overview, Architecture, Repository Structure, Technology Stack, Development Setup, Coding Standards, Project Rules, Testing Strategy, and Known Issues - Includes recommended sections: External integrations (AST CLI, Azure Pipelines, GitHub), Deployment info, Performance considerations, API/Endpoints, Security & Access, Logging, and Debugging Steps - Covers design patterns (Multiton, Semaphore, Configuration) - Detailed setup instructions for Windows and Linux - Comprehensive testing strategy with coverage thresholds and Jest configuration - Security guidelines for authentication, credentials, and proxy management - Debugging guide with common issues and solutions - Contributing and release process documentation Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

github-actions · 2026-04-22T08:03:32Z

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

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

cx-atish-jadhav

Thanks for putting this together — the structure is solid and hits every section the Jira epic calls out. However, I found several claims that don't match the current state of the repo. Leaving inline comments below; most are quick fixes. Happy to chat if any are unclear.

cx-atish-jadhav · 2026-04-24T10:24:24Z

+│   │   │   ├── ExecutionService.ts
+│   │   │   ├── CxCommandOutput.ts
+│   │   │   ├── CxParamType.ts
+│   │   │   ├── loggerConfig.ts


Missing CxWrapperFactory.ts — it exists at src/main/wrapper/CxWrapperFactory.ts and should be listed here alongside the other wrapper files.

cx-atish-jadhav · 2026-04-24T10:24:24Z

+│   │   │   ├── CxCommandOutput.ts
+│   │   │   ├── CxParamType.ts
+│   │   │   ├── loggerConfig.ts
+│   │   │   └── resources/      # Binary resources


This folder doesn't exist in the repo. tsconfig.json:20 also references it — likely stale in both places. Please remove it from the tree (and consider cleaning up tsconfig.json separately).

cx-atish-jadhav · 2026-04-24T10:24:24Z

+│   │   │   └── CxLearnMoreSamples.ts
+│   │   ├── predicates/         # Predicate operations
+│   │   │   └── CxPredicate.ts
+│   │   └── index.ts            # Main export file


There is no src/main/index.ts in the repo. package.json uses dist/main/wrapper/CxWrapper.js as the main entry instead. Either remove this line or create the index file.

cx-atish-jadhav · 2026-04-24T10:24:24Z

+│   │   │   └── CxPredicate.ts
+│   │   └── index.ts            # Main export file
+│   └── tests/
+│       ├── unit/               # Unit tests


Misleading — most *Test.test.ts files live directly under src/tests/ (AuthTest, ChatTest, MaskTest, ProjectTest, ResultTest, ScanTest, etc.). Only AstClientCreateProxyRequestHandler.test.ts is in unit/. Please reflect the actual layout.

cx-atish-jadhav · 2026-04-24T10:24:24Z

+- **node-fetch**: ^3.3.2 - Fetch API for Node.js
+- **tar**: ^7.5.11 - TAR archive handling
+- **unzipper**: ^0.12.3 - ZIP archive extraction
+- **tunnel**: (used indirectly) - HTTPS over HTTP tunneling for proxies


tunnel is imported directly in src/main/client/AstClient.ts:4 (import * as tunnel from 'tunnel';), but it is not declared in package.json dependencies — it currently resolves transitively. Description should be corrected, and ideally tunnel should be added as a direct dependency so the package doesn't break if the transitive dep changes.

cx-atish-jadhav · 2026-04-24T10:24:24Z

+### Publishing a New Version
+
+1. Update version in `package.json`
+2. Update CHANGELOG.md


Same as line 321 — no CHANGELOG.md exists in the repo, so this step isn't actionable as written.

cx-atish-jadhav · 2026-04-24T10:24:24Z

+- `update-cli.yml` - Updates AST CLI binary reference
+- `nightly.yml` - Nightly build and test run
+- `auto-merge-pr.yml` - Auto-merges dependency updates
+- `dependabot-auto-merge.yml` - Dependabot PR automation


This list is missing two workflows that exist in .github/workflows/: delete-packages-and-releases.yml and pr-automation.yml. Please add them.

cx-atish-jadhav · 2026-04-24T10:24:24Z

+
+```typescript
+class CxWrapper {
+  static getInstance(config: CxConfig): Promise<CxWrapper>


Wrong signature. Actual signature in src/main/wrapper/CxWrapper.ts:53 is static async getInstance(cxScanConfig: CxConfig, logFilePath: string): Promise<CxWrapper> — logFilePath is a required second argument.

cx-atish-jadhav · 2026-04-24T10:24:24Z

+  static getInstance(config: CxConfig): Promise<CxWrapper>
+  config: CxConfig
+  cxInstaller: CxInstaller
+  scanWithCLI(params: CxParamType[]): Promise<CxCommandOutput>


scanWithCLI does not exist on CxWrapper. The actual scan-related methods are scanCreate, scanCancel, scanShow, scanList, scanAsca, etc. (see src/main/wrapper/CxWrapper.ts:125 onward). Replace this with the real methods or drop the line.

cx-atish-jadhav · 2026-04-24T10:24:24Z

+- `tenant`: Tenant identifier
+- `pathToExecutable`: Path to AST CLI binary
+- `additionalParameters`: Extra CLI arguments
+- `proxy`: HTTP proxy configuration (via environment)


CxConfig does not have a proxy property — see src/main/wrapper/CxConfig.ts. Proxy is read only from the HTTP_PROXY env var inside AstClient. Please remove this bullet to avoid misleading readers.

cx-rahul-pidde and others added 3 commits April 15, 2026 21:01

fixed lodash vuln.

7dd6b7e

Merge branch 'main' of https://github.com/Checkmarx/ast-cli-javascrip…

07a963e

…t-wrapper-runtime-cli

cx-rahul-pidde requested a review from cx-anurag-dalke as a code owner April 22, 2026 08:00

cx-rahul-pidde requested a review from cx-umesh-waghode April 22, 2026 08:00

cx-atish-jadhav requested changes Apr 24, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

Add standardized CLAUDE.md documentation for ast-cli-javascript-wrapper-runtime-cli (AST-146806)#202
cx-rahul-pidde wants to merge 3 commits intomainfrom
feature/AST-146806-add-claude-md

cx-rahul-pidde commented Apr 22, 2026

Uh oh!

github-actions Bot commented Apr 22, 2026

Uh oh!

cx-atish-jadhav left a comment

Uh oh!

cx-atish-jadhav Apr 24, 2026

Uh oh!

cx-atish-jadhav Apr 24, 2026

Uh oh!

cx-atish-jadhav Apr 24, 2026

Uh oh!

cx-atish-jadhav Apr 24, 2026

Uh oh!

cx-atish-jadhav Apr 24, 2026

Uh oh!

cx-atish-jadhav Apr 24, 2026

Uh oh!

cx-atish-jadhav Apr 24, 2026

Uh oh!

cx-atish-jadhav Apr 24, 2026

Uh oh!

cx-atish-jadhav Apr 24, 2026

Uh oh!

cx-atish-jadhav Apr 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

cx-rahul-pidde commented Apr 22, 2026

Summary

Overview

Key Features

Documentation Highlights

Architecture Section

Development Setup

Coding Standards

Testing Strategy

Security & Access

Debugging Guide

Changes Made

Acceptance Criteria

Related Issues

Testing

Uh oh!

github-actions Bot commented Apr 22, 2026

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

Uh oh!

cx-atish-jadhav left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants