feat(format): Enhance format module with rollback, diff reporting, and improved parallel execution
This commit is contained in:
187
readme.hints.md
187
readme.hints.md
@@ -1 +1,188 @@
|
||||
# Gitzone CLI - Development Hints
|
||||
|
||||
* the cli of the git.zone project.
|
||||
|
||||
## Project Overview
|
||||
|
||||
Gitzone CLI (`@git.zone/cli`) is a comprehensive toolbelt for streamlining local development cycles. It provides utilities for:
|
||||
- Project initialization and templating (via smartscaf)
|
||||
- Code formatting and standardization
|
||||
- Version control and commit management
|
||||
- Docker and CI/CD integration
|
||||
- Meta project management
|
||||
|
||||
## Architecture
|
||||
|
||||
### Core Structure
|
||||
- Main CLI entry: `cli.ts` / `cli.child.ts`
|
||||
- Modular architecture with separate modules in `ts/mod_*` directories
|
||||
- Each module handles specific functionality (format, commit, docker, etc.)
|
||||
- Extensive use of plugins pattern via `plugins.ts` files
|
||||
|
||||
### Configuration Management
|
||||
- Uses `npmextra.json` for all tool configuration
|
||||
- Configuration stored under `gitzone` key in npmextra
|
||||
- No separate `.gitzonerc` file - everything in npmextra.json
|
||||
- Project type and module metadata also stored in npmextra
|
||||
|
||||
### Format Module (`mod_format`) - SIGNIFICANTLY ENHANCED
|
||||
|
||||
The format module is responsible for project standardization:
|
||||
|
||||
#### Current Modules:
|
||||
1. **cleanup** - Removes obsolete files (yarn.lock, tslint.json, etc.)
|
||||
2. **copy** - File copying with glob patterns (fully implemented)
|
||||
3. **gitignore** - Creates/updates .gitignore from templates
|
||||
4. **license** - Checks dependency licenses for compatibility
|
||||
5. **npmextra** - Manages project metadata and configuration
|
||||
6. **packagejson** - Formats and updates package.json
|
||||
7. **prettier** - Applies code formatting with batching
|
||||
8. **readme** - Ensures readme files exist
|
||||
9. **templates** - Updates project templates based on type
|
||||
10. **tsconfig** - Formats TypeScript configuration
|
||||
|
||||
#### Execution Order (Dependency-Based):
|
||||
- Modules are now executed in parallel groups based on dependencies
|
||||
- Independent modules run concurrently for better performance
|
||||
- Dependency analyzer ensures correct execution order
|
||||
|
||||
### New Architecture Features
|
||||
|
||||
1. **BaseFormatter Pattern**: All formatters extend abstract BaseFormatter class
|
||||
2. **FormatContext**: Central state management across all modules
|
||||
3. **FormatPlanner**: Implements plan → action workflow
|
||||
4. **RollbackManager**: Full backup/restore capabilities
|
||||
5. **ChangeCache**: Tracks file changes to optimize performance
|
||||
6. **DependencyAnalyzer**: Manages module execution order
|
||||
7. **DiffReporter**: Generates diff views for changes
|
||||
8. **FormatStats**: Comprehensive execution statistics
|
||||
|
||||
### Key Patterns
|
||||
|
||||
1. **Plugin Architecture**: All dependencies imported through `plugins.ts` files
|
||||
2. **Streaming**: Uses smartstream for file processing
|
||||
3. **Interactive Prompts**: smartinteract for user input
|
||||
4. **Enhanced Error Handling**: Comprehensive try-catch with automatic rollback
|
||||
5. **Template System**: Templates handled by smartscaf, not directly by gitzone
|
||||
6. **Type Safety**: Full TypeScript with interfaces and type definitions
|
||||
|
||||
### Important Notes
|
||||
|
||||
- `.nogit/` directory used for temporary/untracked files, backups, and cache
|
||||
- `.nogit/gitzone-backups/` stores format operation backups
|
||||
- `.nogit/gitzone-cache/` stores file change cache
|
||||
- Templates are managed by smartscaf - improvements should be made there
|
||||
- License checking configurable with exceptions support
|
||||
- All features implemented: `ensureDependency`, copy module, etc.
|
||||
|
||||
## Recent Improvements (Completed)
|
||||
|
||||
1. **Plan → Action Workflow**: Shows changes before applying them
|
||||
2. **Rollback Mechanism**: Full backup and restore on failures
|
||||
3. **Enhanced Configuration**: Granular control via npmextra.json
|
||||
4. **Better Error Handling**: Detailed errors with recovery options
|
||||
5. **Performance Optimizations**: Parallel execution and caching
|
||||
6. **Reporting**: Diff views, statistics, verbose logging
|
||||
7. **Architecture**: Clean separation of concerns with new classes
|
||||
|
||||
## Development Tips
|
||||
|
||||
- Always check readme.plan.md for ongoing improvement plans
|
||||
- Use npmextra.json for any new configuration options
|
||||
- Keep modules focused and single-purpose
|
||||
- Maintain the existing plugin pattern for dependencies
|
||||
- Test format operations on sample projects before deploying
|
||||
- Consider backward compatibility when changing configuration structure
|
||||
- Use BaseFormatter pattern for new format modules
|
||||
- Leverage FormatContext for cross-module state sharing
|
||||
|
||||
## Configuration Examples
|
||||
|
||||
```json
|
||||
{
|
||||
"gitzone": {
|
||||
"format": {
|
||||
"interactive": true,
|
||||
"parallel": true,
|
||||
"showStats": true,
|
||||
"cache": {
|
||||
"enabled": true,
|
||||
"clean": true
|
||||
},
|
||||
"rollback": {
|
||||
"enabled": true,
|
||||
"autoRollbackOnError": true,
|
||||
"backupRetentionDays": 7
|
||||
},
|
||||
"modules": {
|
||||
"skip": ["prettier"],
|
||||
"only": [],
|
||||
"order": []
|
||||
},
|
||||
"licenses": {
|
||||
"allowed": ["MIT", "Apache-2.0"],
|
||||
"exceptions": {
|
||||
"some-package": "GPL-3.0"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## CLI Usage
|
||||
|
||||
```bash
|
||||
# Basic format
|
||||
gitzone format
|
||||
|
||||
# Dry run to preview changes
|
||||
gitzone format --dry-run
|
||||
|
||||
# Non-interactive mode
|
||||
gitzone format --yes
|
||||
|
||||
# Plan only (no execution)
|
||||
gitzone format --plan-only
|
||||
|
||||
# Save plan for later
|
||||
gitzone format --save-plan format.json
|
||||
|
||||
# Execute saved plan
|
||||
gitzone format --from-plan format.json
|
||||
|
||||
# Verbose mode
|
||||
gitzone format --verbose
|
||||
|
||||
# Detailed diff views
|
||||
gitzone format --detailed
|
||||
|
||||
# Rollback operations
|
||||
gitzone format --rollback
|
||||
gitzone format --rollback <operation-id>
|
||||
gitzone format --list-backups
|
||||
gitzone format --clean-backups
|
||||
```
|
||||
|
||||
## Common Issues (Now Resolved)
|
||||
|
||||
1. ✅ Format operations are now reversible with rollback
|
||||
2. ✅ Enhanced error messages with recovery suggestions
|
||||
3. ✅ All modules fully implemented (including copy)
|
||||
4. ✅ Dry-run capability available
|
||||
5. ✅ Extensive configuration options available
|
||||
|
||||
## Future Considerations
|
||||
|
||||
- Plugin system for custom formatters
|
||||
- Git hooks integration for pre-commit formatting
|
||||
- Advanced UI with interactive configuration
|
||||
- Format presets for common scenarios
|
||||
- Performance benchmarking tools
|
||||
|
||||
## API Changes
|
||||
|
||||
- smartfile API updated to use fs.* and memory.* namespaces
|
||||
- smartnpm requires instance creation: `new NpmRegistry()`
|
||||
- All file operations now use updated APIs
|
||||
- Type imports use `import type` for proper verbatim module syntax
|
||||
Reference in New Issue
Block a user