Apply P0 and P1 philosophy fixes: typed exceptions and bug fixes

P0 - Bug Fixes:
- TestRunner auto-discovery: Fixed non-recursive test discovery (ext/TestRunner.jl:614)
  Now uses _collect_test_files_recursive instead of flat readdir

P1 - Typed Exceptions (Tenet 6):
Replaced all untyped error() and ArgumentError with structured CTBase exceptions

P1a - src/Exceptions/types.jl:
- Fixed 2 occurrences of invalid Julia syntax catch e::CTBase.Exceptions.CTException
  → catch e + e isa ... || rethrow()

P1b - ext/TestRunner.jl (7 replacements):
- 3 × error() in _resolve_test → CTBase.Exceptions.IncorrectArgument
- 1 × error() in _run_single_test (function missing after include) → PreconditionError
- 1 × error() in run_tests (subdirectory "test" forbidden) → PreconditionError
- 2 × ArgumentError in _normalize_available_tests → IncorrectArgument

P1c - ext/CoveragePostprocessing.jl (4 replacements):
- 4 × error() → PreconditionError

P1d - ext/DocumenterReference.jl (2 replacements):
- public && private both false → IncorrectArgument
- Invalid element in primary_modules → IncorrectArgument

P1e - ext/TestRunner.jl docstring:
- Fixed incorrect output in _progress_bar docstring (width=20 → 10 blocks, not 20)

P1f - Test updates:
- Updated 7 test files to reflect new exception types

Code cleanup:
- Removed circular import using CTBase from src/Exceptions/Exceptions.jl
- Removed redundant using DocStringExtensions from src/Descriptions/types.jl

All tests pass: 1161/1161

Author: ocots

ext/CoveragePostprocessing.jl

@@ -88,31 +88,28 @@ function CTBase.postprocess_coverage(
 
     n_cov = _count_cov_files(source_dirs)
     if n_cov == 0
-        error("""
-        Coverage requested but no .cov files were produced.
-
-        Expected locations:
-          - src/*.cov
-          - test/*.cov
-          - ext/*.cov
-
-        Did you run:
-          Pkg.test(...; coverage=true) ?
-        """)
+        throw(CTBase.Exceptions.PreconditionError(
+            "Coverage requested but no .cov files were produced",
+            reason="no .cov files found in src/, test/, or ext/",
+            suggestion="run Pkg.test(...; coverage=true) to generate coverage data",
+        ))
     end
 
     _clean_stale_cov_files!(source_dirs)
 
     n_cov = _count_cov_files(source_dirs)
-    n_cov == 0 &&
-        error("Coverage requested but no usable .cov files were found after cleanup.")
+    n_cov == 0 && throw(CTBase.Exceptions.PreconditionError(
+        "Coverage requested but no usable .cov files were found after cleanup",
+    ))
 
     generate_report && _generate_coverage_reports!(
         source_dirs, coverage_dir, root_dir, worst_n_files, max_uncovered_lines
     )
 
     moved = _collect_and_move_cov_files!(source_dirs, cov_storage_dir)
-    isempty(moved) && error("Coverage requested but no .cov files were found to move.")
+    isempty(moved) && throw(CTBase.Exceptions.PreconditionError(
+        "Coverage requested but no .cov files were found to move",
+    ))
     println("✓ Moved $(length(moved)) .cov files to $cov_storage_dir")
 
     println("✓ Coverage post-processing completed successfully")
@@ -295,7 +292,9 @@ function _generate_coverage_reports!(
         append!(cov_all, Coverage.process_folder(dir))
     end
 
-    isempty(cov_all) && error("No coverage data found in source directories")
+    isempty(cov_all) && throw(CTBase.Exceptions.PreconditionError(
+        "No coverage data found in source directories",
+    ))
 
     lcov_file = joinpath(coverage_dir, "lcov.info")
     Coverage.LCOV.writefile(lcov_file, cov_all)

ext/DocumenterReference.jl

@@ -233,9 +233,10 @@ function CTBase.automatic_reference_documentation(
 )
     # Validate arguments
     if !public && !private
-        error(
-            "automatic_reference_documentation: both `public` and `private` cannot be false.",
-        )
+        throw(CTBase.Exceptions.IncorrectArgument(
+            "both `public` and `private` cannot be false",
+            context="automatic_reference_documentation",
+        ))
     end
 
     # Parse primary_modules into a Dict{Module, Vector{String}}
@@ -387,9 +388,11 @@ function _parse_primary_modules(primary_modules::Vector)
             files = last(m)
             result[mod] = _normalize_paths(files isa Vector ? files : [files])
         else
-            error(
+            throw(CTBase.Exceptions.IncorrectArgument(
                 "Invalid element in primary_modules: expected Module or Module => files pair",
-            )
+                got=string(typeof(m)),
+                context="_parse_primary_modules",
+            ))
         end
     end
     return result

ext/TestRunner.jl

@@ -154,12 +154,11 @@ function CTBase.run_tests(
     # Guard: a subdirectory named "test" inside test_dir would conflict with
     # the automatic `test/` prefix stripping in _parse_test_args.
     if isdir(joinpath(test_dir, "test"))
-        error(
-            "A subdirectory \"test\" exists inside the test directory " *
-            "\"$(test_dir)\". This is not supported because selection " *
-            "arguments starting with \"test/\" are automatically stripped " *
-            "(e.g. \"test/suite\" → \"suite\"). Please rename the subdirectory.",
-        )
+        throw(CTBase.Exceptions.PreconditionError(
+            "A subdirectory \"test\" exists inside the test directory \"$(test_dir)\"",
+            reason="selection arguments starting with \"test/\" are automatically stripped (e.g. \"test/suite\" → \"suite\")",
+            suggestion="rename the subdirectory to avoid the conflict",
+        ))
     end
 
     # Parse command-line arguments
@@ -194,7 +193,6 @@ function CTBase.run_tests(
             @testset "$(spec)" begin
                 _run_single_test(
                     spec;
-                    available_tests=available_tests_vec,
                     filename_builder,
                     funcname_builder,
                     eval_mode,
@@ -480,15 +478,21 @@ function _normalize_available_tests(available_tests)
     available_tests === nothing && return TestSpec[]
 
     if !(available_tests isa AbstractVector || available_tests isa Tuple)
-        throw(ArgumentError("available_tests must be a Vector or Tuple of Symbol/String"))
+        throw(CTBase.Exceptions.IncorrectArgument(
+            "available_tests must be a Vector or Tuple of Symbol/String",
+            got=string(typeof(available_tests)),
+        ))
     end
 
     out = TestSpec[]
     for entry in available_tests
         if entry isa Symbol || entry isa String
             push!(out, entry)
         else
-            throw(ArgumentError("available_tests entries must be Symbol or String"))
+            throw(CTBase.Exceptions.IncorrectArgument(
+                "available_tests entries must be Symbol or String",
+                got=string(typeof(entry)),
+            ))
         end
     end
     return out
@@ -609,47 +613,11 @@ function _select_tests(
     filename_builder::Function;
     test_dir::String=joinpath(pwd(), "test"), # Default assumption
 )
-    # 1. Identify all potential test files
-    # We look for .jl files in test_dir, excluding runtests.jl
-    all_files = filter(f -> endswith(f, ".jl") && f != "runtests.jl", readdir(test_dir))
-
-    # Map filenames back to "test names" is tricky without reverse builder.
-    # Strategy:
-    # We assume `available_tests` defines the canonical list of "names".
-    # If `available_tests` is empty, we derive names from files? 
-    #   -> User said: "list all .jl files... but only keep available if provided"
-
     candidates = TestSpec[]
 
     if isempty(available_tests)
-        # If no available_tests provided, every .jl file is a candidate!
-        # This effectively AUTO-DISCOVERS tests.
-        # We need to guess the "name" from the filename.
-        # This is hard because filename_builder is name -> filename.
-        #   utils -> test_utils.jl
-        #   test_utils.jl -> utils ??
-        # For now, let's keep the user's current behavior:
-        # If available_tests is empty, the logic relies on what the user passes.
-        # BUT the new logic says "if args empty -> run all".
-        # So we MUST perform auto-discovery if we want "run all" to work without explicit available_tests.
-
-        # Heuristic: if file starts with "test_", strip it?
-        # Or just use the basename as the symbol?
-        # Let's assume the "name" is the filename without extension for auto-discovery?
-        # Or better: don't guess names yet. Just work with filenames?
-        # But `run_tests` iterates over `names`.
-
-        # Let's look at existing files: test_utils.jl -> name=:utils (via filename_builder)
-        # We cannot invert `filename_builder` (F -> S).
-        # So we are stuck if we want to infer names from files.
-
-        # COMPROMISE: If available_tests is empty, we cannot guarantee auto-discovery compatibility with arbitrary filename_builders.
-        # We will assume a default mapping for auto-discovery: name = file_basename_without_extension.
-        for f in all_files
-            name_str = replace(f, ".jl" => "")
-            # If name starts with "test_", removing it is common convention, but maybe risky?
-            # Let's keep the full basename as the name if we are auto-discovering.
-            push!(candidates, Symbol(name_str))
+        for f in _collect_test_files_recursive(test_dir)
+            push!(candidates, f)
         end
     else
         # If available_tests IS provided, we only consider these.
@@ -764,7 +732,6 @@ This helper:
 
 # Arguments
 - `spec::TestSpec`: Test specification to run
-- `available_tests::AbstractVector{<:TestSpec}`: Available tests for validation
 - `filename_builder::Function`: Function to map test names to filenames
 - `funcname_builder::Function`: Function to map test names to function names
 - `eval_mode::Bool`: Whether to evaluate the function after include
@@ -780,7 +747,6 @@ This helper:
 """
 function _run_single_test(
     spec::TestSpec;
-    available_tests::AbstractVector{<:TestSpec},
     filename_builder::Function,
     funcname_builder::Function,
     eval_mode::Bool,
@@ -792,18 +758,19 @@ function _run_single_test(
 )
     # --- Resolve filename and func_symbol ---
     filename, func_symbol = _resolve_test(
-        spec; available_tests, filename_builder, funcname_builder, eval_mode, test_dir
+        spec; filename_builder, funcname_builder, eval_mode, test_dir
     )
 
     # --- Include the file ---
     Base.include(Main, filename)
 
     # --- Check function exists after include ---
     if eval_mode && func_symbol !== nothing && !isdefined(Main, func_symbol)
-        error("""
-        Function "$(func_symbol)" not found after including "$(filename)".
-        Make sure the file defines a function with this name.
-        """)
+        throw(CTBase.Exceptions.PreconditionError(
+            "Function \"$(func_symbol)\" not found after including \"$(filename)\"",
+            reason="the file does not define a function with this name",
+            suggestion="make sure the file defines a top-level function named $(func_symbol)",
+        ))
     end
 
     # --- on_test_start callback ---
@@ -879,7 +846,6 @@ Raises errors if the file is not found or if `eval_mode=true` but no function ca
 
 # Arguments
 - `spec::TestSpec`: Test specification to resolve
-- `available_tests::AbstractVector{<:TestSpec}`: Available tests for validation
 - `filename_builder::Function`: Function to map test names to filenames
 - `funcname_builder::Function`: Function to map test names to function names
 - `eval_mode::Bool`: Whether to resolve a function name
@@ -900,7 +866,6 @@ Raises errors if the file is not found or if `eval_mode=true` but no function ca
 """
 function _resolve_test(
     spec::TestSpec;
-    available_tests::AbstractVector{<:TestSpec},
     filename_builder::Function,
     funcname_builder::Function,
     eval_mode::Bool,
@@ -910,10 +875,10 @@ function _resolve_test(
         rel = _ensure_jl(spec)
         filename = joinpath(test_dir, rel)
         if !isfile(filename)
-            error("""
-            Test file "$(filename)" not found.
-            Current directory: $(pwd())
-            """)
+            throw(CTBase.Exceptions.IncorrectArgument(
+                "Test file \"$(filename)\" not found",
+                context="current directory: $(pwd())",
+            ))
         end
 
         func_symbol = if eval_mode
@@ -929,30 +894,29 @@ function _resolve_test(
 
     # Build filename
     rel = _find_symbol_test_file_rel(name, filename_builder; test_dir=test_dir)
-    rel === nothing && error("""
-    Test file not found for test "$(name)".
-    Current directory: $(pwd())
-    """)
+    rel === nothing && throw(CTBase.Exceptions.IncorrectArgument(
+        "Test file not found for test \"$(name)\"",
+        context="current directory: $(pwd())",
+    ))
 
     filename = joinpath(test_dir, rel)
 
     # Check file exists
-    !isfile(filename) && error("""
-        Test file "$(filename)" not found for test "$(name)".
-        Current directory: $(pwd())
-        """)
+    !isfile(filename) && throw(CTBase.Exceptions.IncorrectArgument(
+        "Test file \"$(filename)\" not found for test \"$(name)\"",
+        context="current directory: $(pwd())",
+    ))
 
     # Determine function name
     func_symbol = funcname_builder(name)
 
     # Check consistency: eval_mode=true but funcname_builder returns nothing
     if eval_mode && func_symbol === nothing
-        error(
-            """
-      Inconsistency: eval_mode=true but funcname_builder returned nothing for test "$(name)".
-      Either set eval_mode=false, or make funcname_builder return a Symbol.
-      """,
-        )
+        throw(CTBase.Exceptions.PreconditionError(
+            "eval_mode=true but funcname_builder returned nothing for test \"$(name)\"",
+            reason="funcname_builder must return a Symbol when eval_mode=true",
+            suggestion="set eval_mode=false, or make funcname_builder return a Symbol",
+        ))
     end
 
     if !eval_mode || func_symbol === nothing
@@ -1086,7 +1050,7 @@ julia> TestRunner._progress_bar(5, 10)
 "[█████░░░░░]"
 
 julia> TestRunner._progress_bar(5, 10; width=20)
-"[████████████████████░░░░░░]"
+"[██████████░░░░░░░░░░]"
 
 julia> TestRunner._progress_bar(0, 10; width=5)
 "[░░░░░]"

src/Descriptions/types.jl

@@ -1,7 +1,5 @@
 # Type definitions for Descriptions module
 
-using DocStringExtensions
-
 """
 $(TYPEDEF)
 

src/Exceptions/Exceptions.jl

@@ -36,8 +36,6 @@ The Exceptions module is organized into thematic files:
 """
 module Exceptions
 
-using CTBase
-
 # Type definitions
 include("types.jl")
 

src/Exceptions/types.jl

@@ -16,7 +16,8 @@ julia> using CTBase
 
 julia> try
            throw(CTBase.Exceptions.IncorrectArgument("invalid input"))
-       catch e::CTBase.Exceptions.CTException
+       catch e
+           e isa CTBase.Exceptions.CTException || rethrow()
            println("Caught a domain-specific exception: ", e)
        end
 Caught a domain-specific exception: IncorrectArgument: invalid input
@@ -31,7 +32,8 @@ catching all exceptions of this family via `catch e::CTException`.
 try
     # code that may throw CTBase exceptions
     risky_operation()
-catch e::CTBase.Exceptions.CTException
+catch e
+    e isa CTBase.Exceptions.CTException || rethrow()
     # handle all CTBase domain errors uniformly
     handle_error(e)
 end

test/suite/extensions/test_coverage_edge_cases.jl

@@ -103,7 +103,6 @@ function test_coverage_edge_cases()
                     err = try
                         TR._run_single_test(
                             :phantom_test;
-                            available_tests=Symbol[],
                             filename_builder=identity,
                             funcname_builder=identity,
                             eval_mode=false,
@@ -114,8 +113,7 @@ function test_coverage_edge_cases()
                         e
                     end
 
-                    @test err isa ErrorException
-                    @test occursin("Test file", err.msg)
+                    @test err isa CTBase.Exceptions.IncorrectArgument
                     @test occursin("not found", err.msg)
 
                 finally

test/suite/extensions/test_coverage_post_process.jl

@@ -22,7 +22,7 @@ function test_coverage_post_process()
                     e
                 end
 
-                @test err isa ErrorException
+                @test err isa CTBase.Exceptions.PreconditionError
                 @test occursin("no .cov files", lowercase(err.msg))
             end
         end

test/suite/extensions/test_documenter_reference.jl

@@ -70,7 +70,7 @@ function test_documenter_reference()
     DR = DocumenterReference
 
     @testset verbose = VERBOSE showtiming = SHOWTIMING "Invalid primary_modules input" begin
-        @test_throws ErrorException CTBase.automatic_reference_documentation(
+        @test_throws CTBase.Exceptions.IncorrectArgument CTBase.automatic_reference_documentation(
             CTBase.Extensions.DocumenterReferenceTag();
             subdirectory="ref",
             primary_modules=["invalid_string"], # String is not Module or Pair
@@ -386,7 +386,7 @@ function test_documenter_reference()
         )
 
         # public=false, private=false should error
-        @test_throws ErrorException CTBase.automatic_reference_documentation(
+        @test_throws CTBase.Exceptions.IncorrectArgument CTBase.automatic_reference_documentation(
             CTBase.Extensions.DocumenterReferenceTag();
             subdirectory="ref",
             primary_modules=[DocumenterReferenceTestMod],