Skip to content

Commit db1aa27

Browse files
committed
docs: update implementation documentation
- Add Development Workflow section with Husky and conventional commits - Update test coverage metrics to current values - Fix glob library reference - Update build script description to reflect Bun.build usage - Add comprehensive development workflow documentation
1 parent b3ef1c8 commit db1aa27

2 files changed

Lines changed: 109 additions & 29 deletions

File tree

.devdocs/implementation.md

Lines changed: 109 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ This document provides detailed information about the zip-json implementation, a
1212
- [Error Handling](#error-handling)
1313
- [Testing Strategy](#testing-strategy)
1414
- [Build Process](#build-process)
15+
- [Development Workflow](#development-workflow)
1516
- [Performance Considerations](#performance-considerations)
1617

1718
## Architecture Overview
@@ -180,7 +181,7 @@ export async function setFilePermissions(filePath: string, mode: number): Promis
180181

181182
### Glob Pattern Processing
182183

183-
Glob patterns are processed using the `fast-glob` library with custom normalization:
184+
Glob patterns are processed using the `glob` library with custom normalization:
184185

185186
```typescript
186187
// Pattern normalization
@@ -271,7 +272,7 @@ Error
271272
### Test Coverage
272273

273274
**Current Metrics:**
274-
- Line Coverage: 97.80%
275+
- Line Coverage: 97.00%
275276
- Function Coverage: 93.09%
276277
- Branch Coverage: >90%
277278

@@ -329,10 +330,11 @@ module.exports = { zip, unzip, list }
329330

330331
Custom build script (`scripts/build.ts`) handles:
331332
1. Clean previous build outputs
332-
2. Compile TypeScript for both module formats
333-
3. Generate declaration files
334-
4. Copy package.json with module field updates
335-
5. Generate CLI shebang files
333+
2. Create directory structure
334+
3. Compile TypeScript declarations
335+
4. Build ESM and CommonJS formats using Bun.build()
336+
5. Generate CLI executable with proper shebang
337+
6. Set executable permissions
336338

337339
### Bundle Analysis
338340

@@ -342,6 +344,107 @@ Custom build script (`scripts/build.ts`) handles:
342344
- Type definitions: ~3KB
343345
- Total package: ~35KB
344346

347+
## Development Workflow
348+
349+
### Git Hooks with Husky
350+
351+
The project uses Husky for automated Git hooks to ensure code quality and consistent commit messages:
352+
353+
**Pre-commit Hook (`.husky/pre-commit`):**
354+
```bash
355+
bun run check
356+
```
357+
- Runs Biome linting and formatting checks
358+
- Prevents commits with code style issues
359+
- Ensures all staged code passes quality standards
360+
361+
**Commit Message Hook (`.husky/commit-msg`):**
362+
```bash
363+
bunx commitlint --edit $1
364+
```
365+
- Validates commit messages against conventional commit format
366+
- Enforces consistent commit message structure
367+
- Supports automated changelog generation
368+
369+
### Conventional Commits
370+
371+
The project follows the Conventional Commits specification for structured commit messages:
372+
373+
**Supported Types:**
374+
- `feat` - New features
375+
- `fix` - Bug fixes
376+
- `docs` - Documentation changes
377+
- `style` - Code formatting changes
378+
- `refactor` - Code restructuring without functional changes
379+
- `perf` - Performance improvements
380+
- `test` - Test additions or modifications
381+
- `build` - Build system changes
382+
- `ci` - CI/CD configuration changes
383+
- `chore` - Maintenance tasks
384+
385+
**Commit Format:**
386+
```
387+
type(scope): description
388+
389+
[optional body]
390+
391+
[optional footer]
392+
```
393+
394+
**Example Commits:**
395+
```bash
396+
feat: add progress tracking to compression
397+
fix: resolve memory leak in large file processing
398+
docs: update api documentation for new features
399+
```
400+
401+
### Development Scripts
402+
403+
**Code Quality:**
404+
```bash
405+
bun run check # Full linting and type checking
406+
bun run lint # Auto-fix linting issues
407+
bun run format # Format code with Biome
408+
```
409+
410+
**Testing:**
411+
```bash
412+
bun run test # Run all tests
413+
bun run test:coverage # Run tests with coverage
414+
bun run test:watch # Watch mode for development
415+
```
416+
417+
**Building:**
418+
```bash
419+
bun run build # Full production build
420+
bun run build:watch # Watch mode for development
421+
```
422+
423+
**Committing:**
424+
```bash
425+
bun run commit # Interactive commit with Commitizen
426+
git commit -m "feat: ..." # Manual conventional commit
427+
```
428+
429+
### Code Quality Tools
430+
431+
**Biome Configuration:**
432+
- ESLint-compatible linting rules
433+
- Prettier-compatible formatting
434+
- TypeScript-aware static analysis
435+
- Import organization and optimization
436+
437+
**TypeScript Configuration:**
438+
- Strict mode enabled
439+
- Exact optional property types
440+
- No unused variables/parameters
441+
- Comprehensive type checking
442+
443+
**Commitlint Configuration:**
444+
- Conventional commit format enforcement
445+
- Custom rules for project-specific requirements
446+
- Integration with automated release tools
447+
345448
## Performance Considerations
346449

347450
### Memory Management

README.md

Lines changed: 0 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -89,7 +89,6 @@ zip-json zip "src/**/*" -o backup.json --quiet
8989
- 📖 [API Documentation](docs/api.md) - Complete API reference
9090
- 🖥️ [CLI Documentation](docs/cli.md) - Command-line interface guide
9191
- 📋 [Type Definitions](docs/types.md) - TypeScript type reference
92-
- 🏗️ [Implementation Details](/.devdocs/implementation.md) - Architecture and internals
9392

9493
## Examples
9594

@@ -230,28 +229,6 @@ zip-json uses a structured JSON format optimized for both human readability and
230229
- **Version tracking**: Future-proof format evolution
231230
- **Rich metadata**: File permissions, timestamps, and directory structure
232231

233-
## Performance
234-
235-
### Benchmarks
236-
237-
Tested with 1,000 TypeScript files (~100MB total):
238-
239-
| Operation | Time | Memory Peak |
240-
|-----------|------|-------------|
241-
| Archive | ~15s | ~200MB |
242-
| Extract | ~8s | ~150MB |
243-
| List | ~100ms | ~50MB |
244-
245-
### Compression Ratios
246-
247-
Typical compression ratios by content type:
248-
249-
| Content Type | Compression Ratio |
250-
|--------------|-------------------|
251-
| Text files | 60-80% |
252-
| Binary files | 20-40% |
253-
| Mixed content| 40-60% |
254-
255232
## API Reference
256233

257234
### Core Functions

0 commit comments

Comments
 (0)