Skip to content

CHANGELOG.md

Latest commit

 

History

History
290 lines (236 loc) · 10.5 KB

CHANGELOG.md

File metadata and controls

290 lines (236 loc) · 10.5 KB
Raw

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[0.6.1] - 2025-09-09

Added

  • Shell Expansion Auto-Fix: Automatically detects and fixes shell expansion issues
    • Detects when patterns like examples/**/* expand to 100+ individual files
    • Automatically reconstructs the original pattern and re-runs the command
    • Shows clear feedback: "Auto-fixing shell expansion: using pattern 'examples/**/*' instead of 386 individual files"
    • Eliminates frustrating errors and provides seamless user experience
  • Pattern Normalization: Automatic directory pattern conversion
    • Converts bare directory names like "examples" to "examples/**"
    • Handles directory paths like "src/core" to "src/core/**"
    • Makes patterns work intuitively without requiring glob knowledge

Changed

  • Error Messages: Improved user experience with friendly, actionable messages
    • "Pattern needs quotes to work properly" instead of technical stack traces
    • Focus on solutions rather than technical explanations
  • Code Quality: Enhanced maintainability and consistency
    • Extracted validateFilterOptions() method to eliminate code duplication
    • Added named constants for validation limits (MAX_PATTERNS: 100, MAX_PATTERN_LENGTH: 1000)
    • Improved test reliability by fixing flaky performance thresholds
  • CLI Infrastructure: Better executable handling
    • Created proper Node.js wrapper following claudekit pattern
    • Improved package.json bin configuration for reliable npm linking
    • Enhanced CLI integration and error handling

Fixed

  • Test Reliability: Resolved intermittent test failures
    • Fixed flaky performance test thresholds
    • Improved array equality checks in FileDiscovery tests
    • More robust timeout handling in integration tests

[0.6.0] - 2025-08-20

Added

  • Format Command Filtering: Added include/exclude pattern support to format command
    • --include <patterns...> - Include file patterns when formatting
    • --exclude <patterns...> - Exclude file patterns when formatting
    • Works with all format types (json, dsl, graph, markdown, tree)
    • Enables "scan once, format many times" workflow for efficient analysis
    • Shows clear filtering statistics to stderr (e.g., "Files: 456 of 1,234")
    • Instant filtering without file system re-scanning
  • Enhanced Workflow: Powerful new analysis patterns
    • Focus on specific directories: --include "src/**"
    • Exclude test files: --exclude "**/*.test.ts"
    • Monorepo package analysis: --include "packages/core/**"
    • Component-focused views: --include "**/*.{tsx,jsx}"

Changed

  • Format Command Documentation: Enhanced README with comprehensive filtering examples
    • Added "Filtering on Format" section with practical workflows
    • Added filtering statistics explanation
    • Added monorepo and component analysis examples
  • CLI Help: Updated format command help to include new filtering options

[0.5.0] - 2025-08-19

Added

  • Tree Format: New ASCII art visualization format for project structure
    • Visual directory tree using ASCII characters (├── └── │)
    • Available via --format tree for any project size
    • 97% token reduction - most efficient format for structure visualization
    • Complements content-focused formats (dsl, graph, markdown)
    • Sorts directories before files, alphabetically within each type
  • Enhanced Format Selection: Improved auto-format selection logic
    • Tree format excluded from auto-selection (manual choice only)
    • Better documentation of when to use each format
  • Comprehensive Testing: Added 18 test cases for tree format functionality
    • Edge cases: empty projects, single files, deep nesting
    • Performance tests for wide structures
    • Integration tests with existing formatter infrastructure

Changed

  • Format Documentation: Enhanced README with comprehensive format selection guide
    • Clear use cases for each format (tree, dsl, graph, markdown)
    • Token budget planning guidelines
    • Project size examples with specific CLI commands
  • CLI Help: Updated format options to include tree
  • Format Auto-Selection: DSL format now default for projects ≤5000 files

Documentation

  • Added format comparison table with token reduction metrics
  • Added practical CLI examples by project size
  • Added tree format example output
  • Updated performance metrics to include tree format

[0.3.0] - 2025-08-17

Breaking Changes

  • BREAKING: Changed default output filename from PROJECT_INDEX.json to .codebasemap
    • This affects scripts and tools that depend on the specific filename
    • See Migration Guide for upgrade instructions

Added

  • Pattern Support: Added comprehensive include/exclude pattern support via CLI options
    • --include <patterns...> - Include files matching glob patterns
    • --exclude <patterns...> - Exclude files matching glob patterns
    • Support for complex glob syntax: **/*.ts, src/{utils,core}/**, packages/*/src/**
    • Pattern validation with helpful error messages
    • Pattern analysis and optimization suggestions in verbose mode
  • Enhanced File Discovery: Extended FileDiscovery class with pattern filtering capabilities
  • Performance Optimizations: Added pattern caching and performance benchmarking
  • Comprehensive Testing: Added extensive test suite for pattern functionality
    • Unit tests for pattern matching logic
    • Integration tests for complex monorepo scenarios
    • Performance tests for large codebases
  • Documentation: Added comprehensive pattern usage guide and troubleshooting documentation

Changed

  • Output Filename: Default output file changed from PROJECT_INDEX.json to .codebasemap
  • CLI Help: Enhanced help text with pattern examples and usage guidance
  • Error Handling: Improved error messages for pattern validation and file discovery
  • Performance: Optimized file discovery for large codebases with pattern filtering

Removed

  • TypeScript Format: Removed experimental TypeScript format output (was causing issues)

Security

  • Pattern Validation: Added security measures to prevent directory traversal and malicious patterns
  • Path Sanitization: Enhanced path validation and relative path enforcement

[0.2.0] - 2025-08-14

Added

  • Enhanced project indexing capabilities
  • Improved dependency resolution
  • Better error handling and validation
  • Comprehensive test suite

Changed

  • Refined output format and structure
  • Improved performance for large codebases

Migration Guides

Migration from 0.2.x to 0.3.0

Breaking Changes Overview

  1. Output filename changed from PROJECT_INDEX.json to .codebasemap
  2. New CLI options for pattern support (backward compatible)

Quick Migration Steps

  1. Update output filename references:

    # Before (0.2.x)
codebase-map scan
# Creates: PROJECT_INDEX.json

# After (0.3.0)
codebase-map scan
# Creates: .codebasemap

  2. Update scripts and tools:

    # Old script
if [ -f "PROJECT_INDEX.json" ]; then
  cat PROJECT_INDEX.json | jq '.files | length'
fi

# New script
if [ -f ".codebasemap" ]; then
  cat .codebasemap | jq '.files | length'
fi

  3. Update CI/CD pipelines:

    # Old GitHub Actions
- name: Generate codebase map
  run: codebase-map scan
- name: Upload artifact
  uses: actions/upload-artifact@v3
  with:
    path: PROJECT_INDEX.json

# New GitHub Actions
- name: Generate codebase map
  run: codebase-map scan
- name: Upload artifact
  uses: actions/upload-artifact@v3
  with:
    path: .codebasemap

Backward Compatibility

  • CLI commands: All existing commands work without changes
  • Output format: JSON structure remains identical
  • API compatibility: Programmatic usage unchanged
  • Configuration: No configuration file changes needed

New Features (Optional)

After upgrading, you can optionally use the new pattern support:

# Focus on source code only
codebase-map scan --include "src/**" --exclude "**/*.test.ts"

# Monorepo package analysis
codebase-map scan --include "packages/*/src/**" --exclude "**/node_modules/**"

# Documentation-focused scan
codebase-map scan --include "docs/**" --include "*.md" --exclude "**/node_modules/**"

Rollback Instructions

If you need to revert to 0.2.x:

  1. Downgrade package:

    npm install codebase-map@0.2.0

  2. Update filename references back:

    # Rename existing file if needed
mv .codebasemap PROJECT_INDEX.json

  3. Remove pattern options from scripts:

    # Remove --include and --exclude options
codebase-map scan  # Basic command only

Version Compatibility Matrix

Feature 0.2.x 0.3.0 Notes
Basic scanning ✅ ✅ Fully compatible
Output format ✅ ✅ JSON structure unchanged
Filename PROJECT_INDEX.json .codebasemap Breaking change
CLI options Basic Enhanced New options available
Pattern support ❌ ✅ New feature
Performance Good Better Optimized

Verification Steps

After upgrading, verify the migration:

  1. Test basic functionality:

    codebase-map scan --verbose
ls -la .codebasemap  # Should exist

  2. Validate output format:

    cat .codebasemap | jq '.version, .files | length'

  3. Test pattern support:

    codebase-map scan --include "src/**" --verbose

Emergency Rollback

If you encounter issues after upgrading:

  1. Immediate rollback:

    npm install codebase-map@0.2.0
mv .codebasemap PROJECT_INDEX.json  # If file exists

  2. Verify rollback:

    codebase-map scan
ls -la PROJECT_INDEX.json  # Should exist

Support

Links