Develop

.gitignore

@@ -42,4 +42,8 @@ reports/
 .vscode/
 .windsurf/
 .cursor/
-.vscode/
+.vscode/
+.extras/
+
+# Temporary test artifacts (created during test runs)
+test/_test_*/

BREAKINGS.md

@@ -15,6 +15,11 @@ This document outlines all breaking changes introduced in CTBase v0.18.0-beta co
 
 ---
 
+## Non-breaking note (0.18.4)
+
+- Test artifacts cleanup: removed `test/extras/` and `test/src/` directories containing demo scripts and temporary build artifacts. No API changes; purely repository hygiene. No migration required.
+- Enhanced TestRunner internal documentation with comprehensive docstrings for helper functions. No functional changes; documentation only. No migration required.
+
 ## Non-breaking note (0.18.3-beta)
 
 - TestRunner progress bar now keeps full resolution up to 50 tests (previously 20) with cumulative coloring; compressed mode beyond 50 retains uniform bar. No breaking API change; purely visual behavior. No migration required.

CHANGELOGS.md

@@ -5,19 +5,25 @@ All notable changes to CTBase will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.18.4] - 2026-03-02
 
 ### 🧹 Maintenance
 
-#### **Git Configuration**
-- Cleaned up gitignore to exclude IDE directories (`.windsurf/`, `.cursor/`)
-- Removed IDE configuration files from git tracking while preserving them locally
-- Improved repository hygiene and reduced noise in version control
+#### **Test Artifacts Cleanup**
 
-#### **Documentation Generation Improvements**
-- **Simplified title system**: Consistent 'Public API' and 'Private API' titles across documentation
-- **Customization parameters**: Added configurable page titles and descriptions for API documentation
-- **Enhanced testing**: Comprehensive tests for customization parameters and title consistency
+- Removed `test/extras/` directory containing progress bar demos and example scripts
+- Removed `test/src/` temporary artifacts from Documenter testing
+- Updated `.gitignore` to exclude `test/_test_*/` pattern for temporary test artifacts
+- Improved repository hygiene by removing 2286 lines of test artifacts
+
+### 📚 Documentation
+
+#### **TestRunner Internal Documentation**
+
+- Added comprehensive docstrings for internal TestRunner helper functions
+- Documented `_FULL_BAR_THRESHOLD` constant and its purpose for progress bar resolution
+- Added detailed documentation for severity mapping functions (`_severity`, `_color_for_severity`, `_block_char_for_severity`)
+- Documented backward compatibility shim `_default_on_test_done` with usage guidance
 
 ## [0.18.3-beta] - 2026-02-19
 
@@ -233,164 +239,18 @@ This major release represents a significant investment in code quality, develope
 ### 🔧 Technical Improvements
 
 #### **Code Quality**
+
 - **Fixed `@ref` conflicts**: All TestRunner references now use fully qualified names
 - **Enhanced error handling**: Better detection and reporting of test failures
 - **Improved type safety**: Comprehensive type annotations throughout
 - **Memory optimization**: Efficient progress bar rendering and failure detection
 
 ---
 
-## [0.18.0-beta] - 2025-02-04
-
-### 🚀 Major Features
-
-#### **Modular Architecture Overhaul**
-- **Complete reorganization** of the codebase into thematic modules:
-
-```text
-src/
-├── Core/           # Fundamental types and utilities
-├── Exceptions/     # Enhanced error handling system
-├── Unicode/        # Unicode character utilities
-├── Descriptions/   # Description management
-└── Extensions/     # Extension system with tag-based dispatch
-```
-
-- **Improved maintainability** through clear separation of concerns
-- **Better testability** with isolated module boundaries
-
-#### **Enhanced Exception System**
-
-- **New exception types** with rich context:
-  - `PreconditionError`: Replaces `UnauthorizedCall` for state-related errors
-  - `ParsingError`: For syntax and structure validation errors
-  - `AmbiguousDescription`: Enhanced with diagnostic capabilities
-  - `ExtensionError`: Improved with feature and context information
-- **Rich error messages** with optional fields for suggestions, context, and diagnostics
-- **User-friendly display** with emojis and structured formatting
-- **Better debugging experience** with detailed error context
-
-#### **Professional Extension System**
-
-- **Tag-based dispatch** for extension points:
-  - `AbstractDocumenterReferenceTag` / `DocumenterReferenceTag`
-  - `AbstractCoveragePostprocessingTag` / `CoveragePostprocessingTag`  
-  - `AbstractTestRunnerTag` / `TestRunnerTag`
-- **Three core extensions**:
-  - `DocumenterReference`: API documentation generation
-  - `CoveragePostprocessing`: Test coverage analysis and reporting
-  - `TestRunner`: Advanced test execution with glob patterns
-- **Clean separation** between extension points and implementations
-
-#### **Advanced Test Runner**
-
-- **Glob pattern support** for test selection
-- **Configurable filename/function name builders**
-- **Dry run mode** for test planning
-- **Recursive test discovery** in subdirectories
-- **Integration with Julia's test ecosystem**
-
-### 📈 Enhancements
-
-#### **Documentation Improvements**
-
-- **Complete documentation rewrite** with modular tutorials
-- **API reference generation** with automatic categorization
-- **Enhanced coverage reporting** with visual summaries
-- **Professional documentation guides** for developers
-
-#### **Testing Infrastructure**
-
-- **Modular test organization** by functionality (not source structure)
-- **Comprehensive test coverage** with quality metrics
-- **Automated code quality checks** with Aqua.jl
-- **Performance and type stability testing**
-
-#### **Developer Experience**
-
-- **Improved error messages** with actionable suggestions
-- **Better Unicode support** for mathematical notation
-- **Enhanced description management** with intelligent completion
-- **Professional project structure** following Julia best practices
-
-### 🔧 Internal Changes
-
-#### **Code Quality**
-
-- **Strict adherence** to Julia style guidelines
-- **Comprehensive type annotations** for better performance
-- **Memory allocation optimization** for critical paths
-- **Extensive documentation** for all public APIs
-
-#### **Testing Standards**
-
-- **Contract-first testing** methodology
-- **Unit and integration test separation**
-- **Mock and fake implementations** for isolated testing
-- **Deterministic and reproducible tests**
-
-#### **Performance**
-
-- **Type stability improvements** throughout the codebase
-- **Reduced memory allocations** in hot paths
-- **Optimized Unicode operations**
-- **Efficient description matching algorithms**
-
-### 📦 Dependencies
-
-#### **New Dependencies**
-
-- `Aqua = "0.8"`: Code quality and consistency checks
-- `OrderedCollections = "1"`: Ordered data structures for testing
-
-#### **Updated Compatibility**
-
-- Julia `1.10+` (increased from `1.8+`)
-- Updated all package compatibility bounds
-
-### 🏗️ Project Structure
-
-#### **New Directory Organization**
-
-```text
-src/
-├── Core/           # Fundamental types and utilities
-├── Exceptions/     # Enhanced error handling system
-├── Unicode/        # Unicode character utilities
-├── Descriptions/   # Description management
-└── Extensions/     # Extension system
-
-test/
-├── suite/          # Modular test suites by functionality
-├── extras/         # Example tests and diagnostics
-└── src/           # Source-level integration tests
-
-docs/
-└── src/           # Modular documentation tutorials
-```
-
-#### **Extension System**
-
-```text
-ext/
-├── CoveragePostprocessing.jl  # Coverage analysis
-├── DocumenterReference.jl    # API documentation
-└── TestRunner.jl             # Advanced test execution
-```
-
-### 🎯 Breaking Changes
-
-See [BREAKINGS.md](BREAKINGS.md) for detailed migration guide.
-
-### 🙏 Acknowledgments
-
-This major release represents a significant investment in code quality, developer experience, and long-term maintainability. The modular architecture provides a solid foundation for future enhancements while maintaining backward compatibility where possible.
-
----
-
 ## [0.17.4] - Previous Release
 
 ### 📝 Previous Changes
+
 - Stable version with basic exception handling
 - Simple description management
 - Basic Unicode utilities

Project.toml

@@ -1,6 +1,6 @@
 name = "CTBase"
 uuid = "54762871-cc72-4466-b8e8-f6c8b58076cd"
-version = "0.18.3-beta"
+version = "0.18.4"
 authors = ["Olivier Cots <olivier.cots@irit.fr>", "Jean-Baptiste Caillau <caillau@univ-cotedazur.fr>"]
 
 [deps]

ext/TestRunner.jl

@@ -953,6 +953,17 @@ end
 # Progress display
 # ============================================================================
 
+"""
+    _FULL_BAR_THRESHOLD
+
+Internal constant defining the maximum number of tests for full-resolution progress bars.
+
+When the total number of tests is ≤ `_FULL_BAR_THRESHOLD` (50), the progress bar displays
+one character per test with cumulative coloring (each test gets its own colored block).
+Beyond this threshold, the bar switches to compressed mode with uniform coloring.
+
+This threshold balances visual clarity with terminal width constraints.
+"""
 const _FULL_BAR_THRESHOLD = 50
 
 """
@@ -1071,14 +1082,52 @@ function _progress_bar(index::Int, total::Int; width::Union{Int,Nothing}=nothing
     return "[" * repeat("█", filled) * repeat("░", w - filled) * "]"
 end
 
+"""
+    _severity(status::Symbol) -> Int
+
+Internal helper to map test status to severity level for display formatting.
+
+# Arguments
+- `status::Symbol`: Test status (`:error`, `:test_failed`, `:skipped`, or success)
+
+# Returns
+- `Int`: Severity level (3=failure, 2=skipped, 1=success)
+"""
 @inline _severity(status::Symbol) = (status == :error || status == :test_failed) ? 3 : (status == :skipped ? 2 : 1)
 
+"""
+    _color_for_severity(sev::Int) -> String
+
+Internal helper to map severity level to ANSI color code.
+
+# Arguments
+- `sev::Int`: Severity level (3=failure, 2=skipped, 1=success)
+
+# Returns
+- `String`: ANSI color escape code (red for failure, yellow for skipped, green for success)
+"""
 @inline function _color_for_severity(sev::Int)
     sev >= 3 && return "\e[31m" # red
     sev == 2 && return "\e[33m" # yellow
     return "\e[32m"             # green
 end
 
+"""
+    _block_char_for_severity(sev::Int) -> String
+
+Internal helper to map severity level to block character for colorblind-friendly display.
+
+Uses distinct glyphs to ensure progress bars are readable without color:
+- Success: █ (solid block)
+- Skipped: ┆ (thin vertical line)
+- Failure: ▚ (diagonal pattern)
+
+# Arguments
+- `sev::Int`: Severity level (3=failure, 2=skipped, 1=success)
+
+# Returns
+- `String`: Unicode block character representing the severity
+"""
 @inline function _block_char_for_severity(sev::Int)
     sev >= 3 && return "▚"  # failure (diagonal)
     sev == 2 && return "┆"   # skipped (thin vertical)
@@ -1254,7 +1303,23 @@ function _make_default_on_test_done(io::IO, total::Int)
     return update
 end
 
-# Backward compatibility shim: keep old name for callers/tests
+"""
+    _default_on_test_done(info::TestRunInfo)
+
+Backward compatibility shim for the default test completion callback.
+
+Creates a fresh stateful callback via [`_make_default_on_test_done`](@ref) and invokes it
+with the given `info`. This function exists for compatibility with existing code/tests that
+expect a stateless callback signature.
+
+For new code, prefer using [`_make_default_on_test_done`](@ref) directly to create a
+persistent callback that maintains test history across multiple invocations.
+
+# Arguments
+- `info::TestRunInfo`: Test execution information
+
+See also: [`_make_default_on_test_done`](@ref)
+"""
 function _default_on_test_done(info::TestRunInfo)
     cb = _make_default_on_test_done(stdout, info.total)
     return cb(info)