From a4cfde0cd2a4822d938bea65f6d7db7e4d5c55bc Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 27 Dec 2025 03:12:43 +0000 Subject: [PATCH] Update documentation for TypeScript support - Created comprehensive TypeScript support documentation (docs/TYPESCRIPT_SUPPORT.md) - Updated CONTEXT_RISK_ANALYSIS.md with TypeScript features - Enhanced README.md with TypeScript section - Added API examples and best practices - Documented package lock file handling strategy Co-authored-by: johndoe6345789 <224850594+johndoe6345789@users.noreply.github.com> --- README.md | 37 ++++ docs/CONTEXT_RISK_ANALYSIS.md | 80 ++++++++- docs/TYPESCRIPT_SUPPORT.md | 317 ++++++++++++++++++++++++++++++++++ 3 files changed, 429 insertions(+), 5 deletions(-) create mode 100644 docs/TYPESCRIPT_SUPPORT.md diff --git a/README.md b/README.md index 44ef441..e4ae38e 100644 --- a/README.md +++ b/README.md @@ -18,9 +18,12 @@ WizardMerge uses a multi-frontend architecture with a high-performance C++ backe - **Features**: - Three-way merge algorithm - Conflict detection and auto-resolution + - Context-aware analysis (TypeScript, Python, C++, Java) + - Intelligent risk assessment - HTTP API endpoints - GitHub Pull Request integration - Pull request conflict resolution + - TypeScript-specific merge support ### Frontends @@ -209,6 +212,40 @@ When `create_branch: true` is set in the API request: - **GitLab**: Use personal access tokens with `read_api` and `read_repository` scopes - Tokens can be passed via `--token` flag or environment variables (`GITHUB_TOKEN`, `GITLAB_TOKEN`) +## TypeScript Support + +WizardMerge includes comprehensive TypeScript support for intelligent merge conflict resolution: + +### Features + +- **Context-Aware Analysis**: Recognizes TypeScript interfaces, types, enums, and arrow functions +- **Risk Assessment**: Detects breaking changes in type definitions and type safety bypasses +- **Package Lock Handling**: Smart detection of package-lock.json, yarn.lock, pnpm-lock.yaml, and bun.lockb files +- **Security Patterns**: Identifies XSS risks (dangerouslySetInnerHTML, innerHTML) and type safety issues (as any, @ts-ignore) + +### Supported TypeScript Patterns + +- Interfaces, type aliases, and enums +- Arrow functions and async functions +- TypeScript imports (import type, namespace imports) +- Function signatures with type annotations +- Export declarations + +### Package Lock Conflicts + +Package lock files are extremely common sources of merge conflicts. WizardMerge: +- Automatically detects package lock files +- Suggests regenerating lock files instead of manual merging +- Supports npm, Yarn, pnpm, and Bun lock files + +**Recommended workflow for lock file conflicts:** +1. Merge `package.json` manually +2. Delete the lock file +3. Run your package manager to regenerate +4. This ensures consistency and avoids corruption + +See [docs/TYPESCRIPT_SUPPORT.md](docs/TYPESCRIPT_SUPPORT.md) for detailed documentation and API examples. + ## Formal Verification WizardMerge includes a formal TLA+ specification that is verified in CI: diff --git a/docs/CONTEXT_RISK_ANALYSIS.md b/docs/CONTEXT_RISK_ANALYSIS.md index 6c45c2b..5583228 100644 --- a/docs/CONTEXT_RISK_ANALYSIS.md +++ b/docs/CONTEXT_RISK_ANALYSIS.md @@ -19,9 +19,15 @@ Context analysis examines the code surrounding merge conflicts to provide better **Supported Languages:** - C/C++ - Python -- JavaScript/TypeScript +- JavaScript/TypeScript (enhanced with TypeScript-specific patterns) - Java +**TypeScript-Specific Features:** +- Detects interfaces, types, and enums +- Recognizes arrow functions and async functions +- Identifies export statements +- Extracts type imports and re-exports + ### Risk Analysis Risk analysis assesses different resolution strategies and provides recommendations. @@ -41,8 +47,16 @@ Risk analysis assesses different resolution strategies and provides recommendati - Large number of changes (>10 lines) - Critical code patterns (delete, eval, system calls, security operations) - API signature changes +- TypeScript interface/type definition changes +- TypeScript type safety bypasses (as any, @ts-ignore, @ts-nocheck) +- XSS vulnerabilities (dangerouslySetInnerHTML, innerHTML) +- Insecure storage of sensitive data - Discarding significant changes from other branch +**Package Lock File Handling:** +- Detects package-lock.json, yarn.lock, pnpm-lock.yaml, and bun.lockb files +- Can be used to apply special merge strategies for dependency files + **Provided Information:** - Risk level (low/medium/high/critical) - Confidence score (0.0 to 1.0) @@ -158,13 +172,61 @@ Key functions: - `analyze_risk_both()`: Assess risk of concatenation - `contains_critical_patterns()`: Detect security-critical code - `has_api_signature_changes()`: Detect API changes +- `has_typescript_interface_changes()`: Detect TypeScript type definition changes +- `is_package_lock_file()`: Identify package lock files + +### TypeScript Support + +The analyzers now include comprehensive TypeScript support: + +**Context Analyzer:** +- Recognizes TypeScript function patterns (async, export, arrow functions) +- Detects TypeScript type structures (interface, type, enum) +- Extracts TypeScript imports (import type, export) + +**Risk Analyzer:** +- Detects TypeScript-specific risks: + - Type safety bypasses: `as any`, `@ts-ignore`, `@ts-nocheck` + - React security issues: `dangerouslySetInnerHTML` + - XSS vulnerabilities: `innerHTML` + - Insecure storage: storing passwords in `localStorage` +- Identifies interface/type definition changes +- Recognizes package lock file conflicts + +**Example: TypeScript Interface Change Detection** +```cpp +std::vector base = { + "interface User {", + " name: string;", + "}" +}; +std::vector modified = { + "interface User {", + " name: string;", + " email: string;", + "}" +}; + +if (has_typescript_interface_changes(base, modified)) { + std::cout << "TypeScript interface changed!" << std::endl; +} +``` + +**Example: Package Lock File Detection** +```cpp +std::string filename = "package-lock.json"; +if (is_package_lock_file(filename)) { + std::cout << "Applying special merge strategy for lock file" << std::endl; +} +``` ## Testing -Comprehensive test coverage with 24 unit tests: -- 7 tests for context analyzer -- 9 tests for risk analyzer -- 8 existing merge tests +Comprehensive test coverage with 46 unit tests: +- 13 tests for context analyzer (including 6 TypeScript tests) +- 16 tests for risk analyzer (including 7 TypeScript tests) +- 8 tests for three-way merge +- 9 tests for Git CLI Run tests: ```bash @@ -172,6 +234,14 @@ cd backend/build ./wizardmerge-tests ``` +TypeScript-specific tests verify: +- Arrow function detection +- Interface, type, and enum extraction +- TypeScript import patterns +- Type definition change detection +- Critical pattern detection (as any, @ts-ignore, etc.) +- Package lock file identification + ## Security All code has been scanned with CodeQL: diff --git a/docs/TYPESCRIPT_SUPPORT.md b/docs/TYPESCRIPT_SUPPORT.md new file mode 100644 index 0000000..6da815c --- /dev/null +++ b/docs/TYPESCRIPT_SUPPORT.md @@ -0,0 +1,317 @@ +# TypeScript Support in WizardMerge + +## Overview + +WizardMerge includes comprehensive TypeScript support with context-aware analysis and intelligent merge risk assessment specifically designed for TypeScript codebases. + +## Features + +### 1. TypeScript Context Awareness + +The context analyzer recognizes TypeScript-specific code patterns: + +**Function Detection:** +- Regular functions: `function myFunc()`, `export function myFunc()` +- Async functions: `async function myFunc()` +- Arrow functions: `const myFunc = () => {}` +- Typed arrow functions: `const myFunc = (x: number) => {}` +- Method signatures: `myMethod(param: string): ReturnType` + +**Type Structures:** +- Interfaces: `interface User { ... }` +- Type aliases: `type Status = 'pending' | 'approved'` +- Enums: `enum Color { Red, Green, Blue }` +- Export declarations: `export interface`, `export type`, `export enum` + +**Import Patterns:** +- Named imports: `import { Component } from 'react'` +- Type imports: `import type { User } from './types'` +- Namespace imports: `import * as utils from './utils'` +- Re-exports: `export { User } from './types'` +- Export all: `export * from './types'` + +### 2. Package Lock Conflict Handling + +WizardMerge intelligently detects package lock files and can apply special merge strategies: + +**Supported Lock Files:** +- `package-lock.json` (npm) +- `yarn.lock` (Yarn) +- `pnpm-lock.yaml` (pnpm) +- `bun.lockb` (Bun) + +**Why Package Locks Are Special:** +Package lock files are notoriously conflict-prone because: +- They're automatically generated +- They change with every dependency update +- Conflicts are extremely common in team environments +- Manual resolution is error-prone + +**Detection API:** +```cpp +#include "wizardmerge/analysis/risk_analyzer.h" + +std::string filename = "package-lock.json"; +if (is_package_lock_file(filename)) { + // Apply special merge strategy + // Suggestion: regenerate lock file instead of manual merge +} +``` + +### 3. TypeScript Merge Risk Analysis + +The risk analyzer includes TypeScript-specific risk factors: + +**Type Safety Risks:** +- **`as any` casts**: Bypasses TypeScript's type system +- **`@ts-ignore`**: Suppresses type errors on next line +- **`@ts-nocheck`**: Disables type checking for entire file + +**Security Risks:** +- **`dangerouslySetInnerHTML`**: React XSS vulnerability vector +- **`innerHTML =`**: Direct DOM manipulation, XSS risk +- **`localStorage.setItem(...password...)`**: Insecure password storage + +**Breaking Changes:** +- Interface modifications (adding/removing/changing properties) +- Type alias changes +- Enum modifications +- Function signature changes with type annotations + +## API Usage Examples + +### Detecting TypeScript Interface Changes + +```cpp +#include "wizardmerge/analysis/risk_analyzer.h" + +std::vector base = { + "interface User {", + " id: number;", + " name: string;", + "}" +}; + +std::vector modified = { + "interface User {", + " id: number;", + " name: string;", + " email: string; // Added field", + "}" +}; + +if (has_typescript_interface_changes(base, modified)) { + std::cout << "Breaking change: Interface modified" << std::endl; + std::cout << "Recommendation: Review all usages of User interface" << std::endl; +} +``` + +### Analyzing TypeScript Code Risk + +```cpp +#include "wizardmerge/analysis/risk_analyzer.h" + +std::vector base = {"const user: User = data;"}; +std::vector ours = {"const user = data as any;"}; +std::vector theirs = {"const user: User = data;"}; + +auto risk = analyze_risk_ours(base, ours, theirs); + +if (risk.affects_critical_section) { + std::cout << "Warning: TypeScript type safety bypassed!" << std::endl; +} + +for (const auto& factor : risk.risk_factors) { + std::cout << "Risk: " << factor << std::endl; +} +// Output: "Risk: Contains critical code patterns (security/data operations)" +``` + +### Full Context Analysis for TypeScript + +```cpp +#include "wizardmerge/analysis/context_analyzer.h" + +std::vector typescript_code = { + "import { useState } from 'react';", + "import type { User } from './types';", + "", + "interface Props {", + " user: User;", + "}", + "", + "export const UserCard = ({ user }: Props) => {", + " const [expanded, setExpanded] = useState(false);", + " return
{user.name}
;", + "};" +}; + +auto context = analyze_context(typescript_code, 7, 9); + +std::cout << "Function: " << context.function_name << std::endl; +// Output: "Function: UserCard" + +std::cout << "Type: " << context.class_name << std::endl; +// Output: "Type: Props" + +std::cout << "Imports:" << std::endl; +for (const auto& import : context.imports) { + std::cout << " - " << import << std::endl; +} +// Output: +// - import { useState } from 'react'; +// - import type { User } from './types'; +``` + +## Integration with Merge Workflow + +### Example: Smart TypeScript Merge + +```cpp +#include "wizardmerge/merge/three_way_merge.h" +#include "wizardmerge/analysis/context_analyzer.h" +#include "wizardmerge/analysis/risk_analyzer.h" + +// Perform three-way merge +auto result = three_way_merge(base_lines, our_lines, their_lines); + +// Analyze each conflict +for (const auto& conflict : result.conflicts) { + // Get context + auto context = analyze_context(base_lines, + conflict.start_line, + conflict.end_line); + + // Check if we're in a TypeScript interface + if (context.class_name.find("interface") != std::string::npos || + context.class_name.find("type") != std::string::npos) { + std::cout << "Conflict in TypeScript type definition: " + << context.class_name << std::endl; + } + + // Assess risks + auto risk_ours = analyze_risk_ours(conflict.base_lines, + conflict.our_lines, + conflict.their_lines); + + if (has_typescript_interface_changes(conflict.base_lines, + conflict.our_lines)) { + std::cout << "Warning: Accepting OURS will change type definitions" + << std::endl; + } + + // Check for type safety violations + if (contains_critical_patterns(conflict.our_lines)) { + std::cout << "Critical: Code contains type safety bypasses!" + << std::endl; + } +} +``` + +### Example: Package Lock Conflict Resolution + +```cpp +#include "wizardmerge/analysis/risk_analyzer.h" + +std::string filename = "package-lock.json"; + +if (is_package_lock_file(filename)) { + std::cout << "Package lock file detected!" << std::endl; + std::cout << "Recommendation: Regenerate instead of merging" << std::endl; + std::cout << "Steps:" << std::endl; + std::cout << " 1. Delete package-lock.json" << std::endl; + std::cout << " 2. Merge package.json manually" << std::endl; + std::cout << " 3. Run 'npm install' to regenerate lock file" << std::endl; + std::cout << " 4. Commit the new lock file" << std::endl; + + // Skip manual merge and suggest regeneration + return; +} +``` + +## Testing + +WizardMerge includes comprehensive tests for TypeScript support: + +### Context Analyzer Tests +- `TypeScriptFunctionDetection`: Verifies async function detection +- `TypeScriptArrowFunctionDetection`: Tests arrow function parsing +- `TypeScriptInterfaceDetection`: Validates interface extraction +- `TypeScriptTypeAliasDetection`: Tests type alias recognition +- `TypeScriptEnumDetection`: Verifies enum parsing +- `TypeScriptImportExtraction`: Tests import statement detection + +### Risk Analyzer Tests +- `TypeScriptInterfaceChangesDetected`: Validates interface change detection +- `TypeScriptTypeChangesDetected`: Tests type alias modifications +- `TypeScriptEnumChangesDetected`: Verifies enum change detection +- `PackageLockFileDetection`: Tests lock file identification +- `TypeScriptCriticalPatternsDetected`: Validates detection of type safety bypasses +- `TypeScriptSafeCodeNoFalsePositives`: Ensures safe code doesn't trigger warnings +- `RiskAnalysisIncludesTypeScriptChanges`: Integration test for risk assessment + +### Running Tests + +```bash +cd backend/build +./wizardmerge-tests --gtest_filter="*TypeScript*" +``` + +All TypeScript tests pass with 100% success rate. + +## Best Practices + +### When Merging TypeScript Code + +1. **Always review interface/type changes**: Breaking changes can affect many files +2. **Watch for type safety bypasses**: `as any`, `@ts-ignore` should be rare +3. **Be cautious with package lock conflicts**: Consider regenerating instead of manual merge +4. **Check import changes**: Missing or duplicate imports can break builds +5. **Validate after merge**: Run TypeScript compiler to catch type errors + +### Package Lock Files + +**Recommended Strategy:** +1. Don't manually merge package lock files +2. Merge `package.json` first +3. Delete the lock file +4. Run package manager to regenerate it +5. This ensures consistency and avoids corruption + +**Why This Works:** +- Lock files are deterministic - given the same `package.json`, you get the same lock +- Manual merging can create invalid dependency trees +- Regeneration is faster and safer than manual resolution + +## Language Support Summary + +| Feature | Support Level | +|---------|--------------| +| Function detection | ✅ Full | +| Arrow functions | ✅ Full | +| Async/await | ✅ Full | +| Interfaces | ✅ Full | +| Type aliases | ✅ Full | +| Enums | ✅ Full | +| Generics | ⚠️ Partial (detected as part of function signatures) | +| Decorators | ⚠️ Partial (detected in context) | +| TSX/JSX | ✅ Full (treated as TypeScript) | +| Import patterns | ✅ Full | +| Type safety validation | ✅ Full | +| Package lock detection | ✅ Full | + +## Future Enhancements + +Potential improvements for TypeScript support: + +1. **Semantic merging**: Parse AST to merge at type level instead of line level +2. **Dependency tree analysis**: Detect impact of type changes across files +3. **Auto-fix suggestions**: Propose specific merge resolutions based on type information +4. **Integration with TypeScript compiler**: Use `tsc` for validation +5. **Package version conflict resolution**: Smart handling of semver ranges in lock files + +## See Also + +- [Context and Risk Analysis Documentation](CONTEXT_RISK_ANALYSIS.md) +- [ROADMAP](../ROADMAP.md) - Phase 2.1: Smart Conflict Resolution +- [Backend API Documentation](../backend/README.md)