package.json Synchronization

Table of Contents

1. Introduction
2. Core Components
3. Architecture Overview
4. Detailed Component Analysis
5. Dependency Analysis
6. Performance Considerations
7. Troubleshooting Guide
8. Conclusion

Introduction

The aicommit tool provides version synchronization functionality for JavaScript projects by updating the version field in package.json files. This feature is part of a broader version management system that supports multiple package formats including npm, Cargo, and custom version files. When enabled via the --version-npm CLI flag, the tool reads the current version from a specified version file, increments it, and propagates this updated version to all relevant configuration files including package.json. The implementation prioritizes data integrity by using safe JSON parsing and serialization through serde_json, preserving formatting and avoiding corruption of existing content.

Core Components

The version synchronization functionality is implemented through several core components in the aicommit codebase. The update_npm_version async function handles the specific logic for modifying package.json files, while the CLI argument parser defined in the Cli struct manages user input for the --version-npm flag. The version incrementing logic is centralized in the increment_version function, which parses semantic version strings and safely increments the patch number. These components work together to provide a reliable version management workflow that integrates with git operations and other package managers.

Section sources

• main.rs
• main.rs
• main.rs

Architecture Overview

graph TD
A[CLI Input] --> B{Check Flags}
B --> |version_file specified| C[Read Version File]
B --> |version_iterate set| D[Increment Version]
C --> E[Store New Version]
D --> E
E --> F{version_npm set?}
F --> |Yes| G[Update package.json]
F --> H{version_cargo set?}
H --> |Yes| I[Update Cargo.toml]
H --> J{version_github set?}
J --> |Yes| K[Create Git Tag]
G --> L[Stage Changes]
I --> L
K --> L
L --> M[Generate Commit Message]
M --> N[Create Git Commit]

Diagram sources

• main.rs

Detailed Component Analysis

update_npm_version Function Analysis

The update_npm_version function implements the core logic for modifying package.json files. It follows a three-step process: read, parse, and write, with comprehensive error handling at each stage.

Implementation Flowchart

flowchart TD
Start([Start]) --> ReadFile["Read package.json"]
ReadFile --> ParseJSON["Parse JSON Content"]
ParseJSON --> ExtractObject{"Is Object?"}
ExtractObject --> |Yes| UpdateVersion["Set version field"]
ExtractObject --> |No| ReturnError["Return Error"]
UpdateVersion --> Serialize["Serialize JSON Pretty"]
Serialize --> WriteFile["Write package.json"]
WriteFile --> End([Success])
ReadFile -.-> IOError["File I/O Error"] --> HandleError["Return Error"]
ParseJSON -.-> ParseError["JSON Parse Error"] --> HandleError
Serialize -.-> SerializeError["Serialization Error"] --> HandleError
WriteFile -.-> WriteError["Write Error"] --> HandleError

Diagram sources

• main.rs

Error Handling Sequence

sequenceDiagram
participant User as "User"
participant CLI as "aicommit CLI"
participant FS as "File System"
User->>CLI : Execute with --version-npm
CLI->>FS : Read package.json
alt File Exists
FS-->>CLI : Return content
CLI->>CLI : Parse JSON
alt Valid JSON
CLI->>CLI : Update version field
CLI->>CLI : Serialize JSON
CLI->>FS : Write updated content
alt Write Success
FS-->>CLI : Success
CLI-->>User : Operation complete
else Write Failure
FS-->>CLI : Error
CLI-->>User : "Failed to write package.json"
end
else Parse Error
CLI-->>User : "Failed to parse package.json"
end
else File Missing
FS-->>CLI : Error
CLI-->>User : "Failed to read package.json"
end

Diagram sources

• main.rs

Section sources

• main.rs

Integration with npm Scripts

The aicommit tool integrates with npm scripts through predefined commands in the package.json file. The new-version script demonstrates how multiple version synchronization flags can be combined into a single workflow that updates both Rust and JavaScript package versions, creates git tags, and pushes changes to the remote repository.

Script Integration Diagram

graph LR
A[npm run new-version] --> B[aicommit --add]
B --> C[--version-file version]
C --> D[--version-iterate]
D --> E[--version-cargo]
E --> F[--version-npm]
F --> G[--version-github]
G --> H[--push]
H --> I[Full Release Workflow]

Diagram sources

• package.json

Section sources

• package.json

Dependency Analysis

The version synchronization feature depends on several external crates that provide essential functionality. The serde_json crate enables safe JSON parsing and serialization, while tokio provides asynchronous file I/O operations. These dependencies are crucial for maintaining data integrity during file operations and preventing race conditions in concurrent environments.

graph LR
A[update_npm_version] --> B[serde_json]
A --> C[tokio::fs]
B --> D[JSON Parsing]
B --> E[JSON Serialization]
C --> F[Async Read]
C --> G[Async Write]
D --> H[Data Integrity]
E --> H
F --> I[Non-blocking I/O]
G --> I

Diagram sources

• main.rs

Section sources

• main.rs
• Cargo.toml

Performance Considerations

The implementation uses asynchronous file operations to prevent blocking the main thread during I/O operations. By leveraging tokio’s async runtime, the tool can perform other tasks while waiting for file system operations to complete. The JSON parsing and serialization are handled efficiently by serde_json, which minimizes memory allocations and processing time. However, since these operations are typically performed infrequently (during version updates), performance optimization is less critical than data integrity and error handling.

Troubleshooting Guide

Common issues with the --version-npm functionality include missing version files, malformed JSON, permission errors, and file locking conflicts. The tool provides descriptive error messages for each failure case, helping users diagnose and resolve problems quickly.

Common Issues and Solutions

Section sources

• main.rs
• main.rs

Conclusion

The package.json synchronization feature in aicommit provides a robust solution for managing version numbers across different package formats. By using safe JSON handling through serde_json and asynchronous file operations via tokio, the implementation ensures data integrity while maintaining good performance. The integration with npm scripts allows for automated release workflows, and comprehensive error handling helps users diagnose and resolve common issues. This functionality exemplifies how modern Rust tools can provide reliable automation for common development tasks while prioritizing safety and correctness.