LiteBuild 0.4.1__tar.gz → 0.7__tar.gz

{litebuild-0.4.1 → litebuild-0.7}/LiteBuild/build_engine.py

@@ -1,24 +1,29 @@
-# build_engine.py
 from concurrent.futures import ProcessPoolExecutor
-from enum import IntEnum
+import datetime
+import difflib
+from enum import IntEnum, StrEnum
 import json
 import os
 from pathlib import Path
 import subprocess
 import time
+import traceback
 from typing import List, Dict, Tuple, NamedTuple, Optional
 
 import networkx as nx
 from YMLEditor.yaml_reader import ConfigLoader
 
+
+# build_engine.py
+
 from LiteBuild.build_logger import BuildLogger, setup_logger, get_logger
 from LiteBuild.command_generator import CommandGenerator
 from LiteBuild.dependency_graph import DependencyGraph
-from LiteBuild.schema import BUILD_SCHEMA, LiteBuildValidator
+from LiteBuild.schema import BUILD_SCHEMA, LiteBuildValidator, YAMLSection
 
 
 class UpdateCode(IntEnum):
-    """Enumeration for why a build step is considered outdated."""
+    """Enumeration for why a build step is  outdated."""
     UP_TO_DATE = 0
     MISSING_OUTPUT = 1
     NOT_TRACKED = 2
@@ -28,6 +33,7 @@ class UpdateCode(IntEnum):
     NEWER_INPUT = 6
     MISSING_INPUT = 7
     STALE_TARGET = 8
+    FORCED = 9
 
 
 class BuildStep(NamedTuple):
@@ -55,13 +61,28 @@ class BuildEngine:
     ):
         """Initializes the BuildEngine, merging command-line variables into the config."""
         if cli_vars:
-            if "GENERAL" not in config_data:
-                config_data["GENERAL"] = {}
-            config_data["GENERAL"].update(cli_vars)
+            if YAMLSection.GENERAL not in config_data:
+                config_data[YAMLSection.GENERAL] = {}
+            config_data[YAMLSection.GENERAL].update(cli_vars)
 
         self.config = config_data
         self.state_file = state_file
 
+        # Validate Input Directory
+        input_dir = config_data.get(YAMLSection.GENERAL, {}).get("INPUT_DIRECTORY")
+        if input_dir:
+            path = Path(input_dir)
+            if not path.exists():
+                raise FileNotFoundError(
+                    f"❌ Configuration Error: INPUT_DIRECTORY does not exist.\n"
+                    f"   Path: {path.absolute()}"
+                )
+            if not path.is_dir():
+                raise NotADirectoryError(
+                    f"❌ Configuration Error: INPUT_DIRECTORY is not a directory.\n"
+                    f"   Path: {path.absolute()}"
+                )
+
     @classmethod
     def from_file(
             cls, config_filepath: str, cli_vars: Optional[Dict] = None,
@@ -76,9 +97,9 @@ class BuildEngine:
             return cls(config_data, cli_vars=cli_vars, state_file=state_file)
         except (FileNotFoundError, ValueError) as e:
             # Re-raise to be handled by the calling script (CLI or GUI)
-            raise e
+            raise
 
-    def execute(self, final_step_name: str, profile_name: str = "", logger: BuildLogger = None):
+    def execute(self, final_step_name: str, profile_name: str = "", logger: BuildLogger = None, status_callback=None, force_rebuild=False):
         """
         Plans and executes the build for a specific workflow entry step.
         """
@@ -86,47 +107,112 @@ class BuildEngine:
             logger = get_logger()
         setup_logger(logger)
 
-        # --- Extract Context info ---
-        general_cfg = self.config.get("GENERAL", {})
-        profile_cfg = self.config.get("PROFILES", {}).get(profile_name, {})
-
-        # Look in General (CLI vars usually land here) or Profile
-        segment = general_cfg.get("SEGMENT") or profile_cfg.get("SEGMENT") or "Unknown"
-        category = general_cfg.get("CATEGORY") or profile_cfg.get("CATEGORY") or "Unknown"
-
-        context_str = f"Segment: {segment}, Category: {category}"
+        context_str = ""
         if profile_name:
-            context_str += f" (Profile: {profile_name})"
+            context_str += f" Profile: {profile_name}"
 
-        logger.log(f"🔵 Executing build for step {final_step_name}")
-        logger.log(f"ℹ️   {context_str}\n")
+        # Format the time as a string (HH:MM:SS) using strftime()
+        current_time = "" #now.strftime("%H:%M:%S")
+
+        logger.log(f"\n🔵 Executing build for target step: {final_step_name} - {current_time}")
+        profile_display = profile_name or "none"
+        logger.log(f"ℹ️   Profile: {profile_display}\n")
 
         try:
             state_manager = BuildStateManager(self.state_file)
             planner = BuildPlanner(self.config, state_manager.load_state())
-            plan = planner.plan_build(profile_name, final_step_name)
-
+            plan = planner.plan_build(profile_name, final_step_name, force_rebuild=force_rebuild)
             executor = BuildExecutor(state_manager, self.config)
-            success = executor.execute_plan(plan, logger)
+            success = executor.execute_plan(plan, logger, status_callback=status_callback)
         except Exception as e:
             success = False
-            logger.log(f"{e}")
+            # ---  ERROR REPORTING ---
+            logger.log(f"🔴{e}")
+
+            # Update status callback if present
+            if status_callback:
+                status_callback("step", 0, 0, "error")
+
+        # Format the time as a string (HH:MM:SS) using strftime()
+        current_time = "" #now.strftime("%H:%M:%S")
 
         if success:
-            logger.log(f"\n✅ Build finished successfully.")
+            logger.log(f"\n✅ Build finished successfully. {current_time}")
+            return True
         else:
-            logger.log(f"🔴Build failed for {final_step_name}")
+            logger.log(f"🔴Build failed for {final_step_name}.  {current_time}")
+            return False
+        
+    def get_group_list(self) -> dict:
+        """Returns the PROFILE_GROUPS in the YAML config."""
+        return self.config.get(YAMLSection.PROFILE_GROUPS, {})
+
+    def get_profile_list(self) -> dict:
+        """Returns the PROFILES in the YAML config."""
+        return self.config.get(YAMLSection.PROFILES, {})
 
     def has_profile(self, profile_name: str) -> bool:
         """Checks if a specific profile key exists in the YAML config."""
-        return profile_name in self.config.get('PROFILES', {})
+        return profile_name in self.get_profile_list()
+
+    def resolve_profile_group(self, group_name: str) -> List[str]:
+        """Resolve a profile group into its ordered list of profile names.
+
+        Args:
+            group_name: Name of the PROFILE_GROUPS entry to resolve.
+
+        Returns:
+            Profile names in the order defined by the configuration.
+
+        Raises:
+            ValueError: If the group does not exist, is empty, or references
+                profiles that are not defined in PROFILES.
+        """
+        profile_groups = self.get_group_list()
+
+        if group_name not in profile_groups:
+            available = list(profile_groups.keys())
+            matches = difflib.get_close_matches(group_name, available, n=1, cutoff=0.6)
+            hint = f"\n   Did you mean '{matches[0]}'?" if matches else ""
+
+            if available:
+                available_text = "\n - ".join(available)
+                available_message = f"\nAvailable profile groups:\n - {available_text}"
+            else:
+                available_message = "\nNo profile groups are configured."
+
+            raise ValueError(
+                f"\nProfile Group '{group_name}' not found.{hint}"
+                f"{available_message}\n"
+            )
+
+        profiles = list(profile_groups[group_name])
+        if not profiles:
+            raise ValueError(
+                f"Profile Group '{group_name}' does not contain any profiles."
+            )
+
+        configured_profiles = self.get_profile_list()
+        missing_profiles = [
+            profile_name
+            for profile_name in profiles
+            if profile_name not in configured_profiles
+        ]
+
+        if missing_profiles:
+            missing_text = "\n - ".join(missing_profiles)
+            raise ValueError(
+                f"Profile Group '{group_name}' references undefined profiles:"
+                f"\n - {missing_text}\n"
+            )
+
+        return profiles
 
     def describe(self, profile_name: str) -> str:
         """Generates a Markdown description of the workflow for a given profile."""
         reporter = BuildReporter(self.config)
         return reporter.describe_workflow(profile_name)
 
-
 class BuildPlanner:
     """
     Analyzes the workflow and build state to create an incremental build plan.
@@ -137,10 +223,22 @@ class BuildPlanner:
         self.build_state = build_state
         self.logger = get_logger()
 
-    def _is_step_outdated(self, command: Dict) -> Tuple[UpdateCode, str]:
+    @staticmethod
+    def _normalize_path(path: str) -> str:
+        """Return a stable absolute path for DAG input/output comparison."""
+        return os.path.normcase(os.path.abspath(os.path.normpath(os.fspath(path))))
+
+    def _is_step_outdated(
+            self, command: Dict, produced_outputs: set[str], force_rebuild: bool = False
+    ) -> Tuple[UpdateCode, str]:
+        # 1. Force Check (Short Circuit)
+        if force_rebuild:
+            self.logger.debug(f"  - RESULT: Rebuild forced by user. (COMMAND_CHANGED)")
+            return UpdateCode.FORCED, ""
+
         """Checks a single step to see if it needs to be rebuilt, with detailed debug logging."""
         output_path = command['output']
-        node_name = command.get('node_name', 'UnknownStep') # Assuming node_name is passed in command dict
+        node_name = command.get('node_name', 'UnknownStep')
 
         self.logger.debug(f"\n--- Checking status of step '{node_name}' ---")
         self.logger.debug(f"  - Output file: '{output_path}'")
@@ -188,7 +286,18 @@ class BuildPlanner:
             for input_file in command['input_files']:
                 self.logger.debug(f"    - Checking input: '{input_file}'")
                 if not os.path.exists(input_file):
-                    self.logger.debug(f"    - RESULT: Input file does not exist. (MISSING_INPUT)")
+                    normalized_input = self._normalize_path(input_file)
+                    if normalized_input in produced_outputs:
+                        self.logger.debug(
+                            "    - RESULT: Input does not exist yet, but is produced by "
+                            "another step in this DAG."
+                        )
+                        continue
+
+                    self.logger.debug(
+                        "    - RESULT: Input file does not exist and is not produced by "
+                        "this DAG. (MISSING_INPUT)"
+                    )
                     raise FileNotFoundError(input_file)
 
                 input_mtime = os.path.getmtime(input_file)
@@ -207,7 +316,7 @@ class BuildPlanner:
         self.logger.debug(f"  - RESULT: Step is up-to-date. (UP_TO_DATE)")
         return UpdateCode.UP_TO_DATE, ""
 
-    def plan_build(self, profile_name: str, final_step_name: str = None) -> BuildPlan:
+    def plan_build(self, profile_name: str, final_step_name: str = None, force_rebuild: bool = False) -> BuildPlan:
         command_map, execution_graph = self._generate_command_map_and_graph(
             profile_name, final_step_name
         )
@@ -215,11 +324,25 @@ class BuildPlanner:
         for node, cmd in command_map.items():
             cmd['node_name'] = node
 
+        produced_outputs = {
+            self._normalize_path(command["output"])
+            for command in command_map.values()
+        }
+
         initially_outdated = {}
         build_order = list(nx.topological_sort(execution_graph))
         for node_name in build_order:
             command = command_map[node_name]
-            update_code, context = self._is_step_outdated(command)
+            update_code, context = self._is_step_outdated(
+                command, produced_outputs, force_rebuild=force_rebuild
+            )
+
+            if update_code == UpdateCode.MISSING_INPUT:
+                raise FileNotFoundError(
+                    f"Cannot build step '{node_name}': required input '{context}' is missing "
+                    "and no step in the current build DAG creates it."
+                )
+
             if update_code != UpdateCode.UP_TO_DATE:
                 initially_outdated[node_name] = (update_code, context)
 
@@ -239,6 +362,14 @@ class BuildPlanner:
                 steps_to_skip.append(BuildStep(node_name, step_command, UpdateCode.UP_TO_DATE, ""))
         return BuildPlan(steps_to_run, steps_to_skip, command_map, execution_graph)
 
+    @staticmethod
+    def get_suggestion(invalid_key: str, valid_options: list[str]) -> str:
+        """Returns a 'Did you mean X?' string if a close match is found."""
+        matches = difflib.get_close_matches(invalid_key, valid_options, n=1, cutoff=0.6)
+        if matches:
+            return f"\n   Did you mean '{matches[0]}'?"
+        return ""
+
     def _generate_command_map_and_graph(self, profile_name: str, final_step_name: str = None) -> \
             Tuple[Dict, nx.DiGraph]:
         """Generates all commands and the dependency graph for a given profile."""
@@ -249,33 +380,40 @@ class BuildPlanner:
                 profile_config = all_profiles[profile_name]
             else:
                 available = "\n - ".join(all_profiles.keys())
+                hint = self.get_suggestion(profile_name, list(all_profiles.keys()))
                 raise ValueError(
-                    f"profile '{profile_name}' not found. Available profiles are:\n - {available}"
+                    f"\nProfile '{profile_name}' not found.{hint}\n"
+                    f"\nAvailable profiles:\n - {available}\n"
                 )
 
         graph_manager = DependencyGraph(self.config.get("WORKFLOW", {}))
         execution_graph = graph_manager.get_execution_subgraph(final_step_name)
-        general_config = self.config.get("GENERAL", {})
-        command_gen = CommandGenerator(general_config, profile_config)
+        general_config = self.config.get(YAMLSection.GENERAL, {})
+        parameters_config = self.config.get(YAMLSection.PARAMETERS, {})
+        command_gen = CommandGenerator(parameters_config, profile_config)
         context = {"profile_name": profile_name, **general_config, **profile_config}
 
         # Pre-process input files to create full paths automatically.
-        input_dir = context.get("INPUT_DIRECTORY")
         input_basenames = context.get("INPUT_FILES")
+        input_dir = context.get("INPUT_DIRECTORY", {})
 
         if input_dir and input_basenames:
-            # Create the list of full paths
             full_paths = [os.path.join(input_dir, f) for f in input_basenames]
-            # Overwrite the INPUT_FILES in the context with the full paths.
-            # This makes the fully resolved list available to all template substitutions.
             context['INPUT_FILES'] = full_paths
 
         command_map, resolved_outputs = {}, {}
         for node_name in nx.topological_sort(execution_graph):
             node_data = execution_graph.nodes[node_name]
-            command_map[node_name] = command_gen.generate_for_node(
-                node_name, node_data, context, resolved_outputs
-            )
+
+            try:
+                command_map[node_name] = command_gen.generate_for_node(
+                    node_name, node_data, context, resolved_outputs
+                )
+            except Exception as e:
+                # This catches errors in CommandGenerator (like invalid format strings)
+                # and adds the context of WHICH rule failed.
+                raise RuntimeError(f"Error generating COMMAND for rule '{node_name}': {e}") from e
+
         return command_map, execution_graph
 
 class BuildExecutor:
@@ -286,33 +424,46 @@ class BuildExecutor:
         self.build_state = state_manager.load_state()
         self.config = config
         self.update_codes = {
-            UpdateCode.UP_TO_DATE: "(Up-to-date)", UpdateCode.MISSING_OUTPUT: "(Creating Output)",
-            UpdateCode.NOT_TRACKED: "(First build)",
-            UpdateCode.COMMAND_CHANGED: "(Command has changed)",
-            UpdateCode.INPUTS_CHANGED: "(Input file list has changed)",
-            UpdateCode.PARAMS_CHANGED: "(Parameters have changed)",
-            UpdateCode.NEWER_INPUT: "(Input '{context}' is newer)",
-            UpdateCode.MISSING_INPUT: "(Input '{context}' is missing)",
-            UpdateCode.STALE_TARGET: "(Target is stale)"
+            UpdateCode.UP_TO_DATE: "", UpdateCode.MISSING_OUTPUT: "(Creating Output)",
+            UpdateCode.NOT_TRACKED: "(first build)",
+            UpdateCode.COMMAND_CHANGED: "(command has changed)",
+            UpdateCode.INPUTS_CHANGED: "(input file list has changed)",
+            UpdateCode.PARAMS_CHANGED: "(parameters have changed)",
+            UpdateCode.NEWER_INPUT: "(input '{context}' is newer)",
+            UpdateCode.MISSING_INPUT: "(input '{context}' is missing)",
+            UpdateCode.STALE_TARGET: "(stale target)",
+            UpdateCode.FORCED: "(forced)"
         }
 
-    def execute_plan(self, plan: BuildPlan, logger: BuildLogger) -> bool:
+    def execute_plan(self, plan: BuildPlan, logger: BuildLogger, status_callback=None) -> bool:
         """Executes the build plan, managing parallel execution and state."""
         total_to_run = len(plan.steps_to_run)
         finished_count = 0
 
-        for step in plan.steps_to_skip:
-            logger.log(f"Skipping '{step.node_name}' (up-to-date)")
+        # Track timing for reporting
+        step_timings = {}
+        build_start_time = time.time()
+
+        # --- Initial Status Update ---
+        if status_callback:
+            status_callback("step", 0, total_to_run, "started")
+
+        if plan.steps_to_skip:
+            skipped = ", ".join(
+                step.node_name for step in plan.steps_to_skip
+            )
+            logger.log(f"⏭️  Skipping up-to-date steps:\n   {skipped}\n")
 
         if not plan.steps_to_run:
+            if status_callback:
+                status_callback("step", 0, 0, "done")
             return True
 
-        # Ask the logger for the information needed to initialize workers.
-        # This is polymorphic: a FileLogger provides info, a StreamLogger does not.
         worker_init_info = logger.get_worker_init_info()
         initializer, initargs = (worker_init_info if worker_init_info else (None, ()))
 
         tasks_to_run_map = {s.node_name: s for s in plan.steps_to_run}
+
         for generation in nx.topological_generations(plan.execution_graph):
             tasks_this_generation = []
             for node_name in generation:
@@ -326,7 +477,7 @@ class BuildExecutor:
             if not tasks_this_generation:
                 continue
 
-            max_workers = self.config.get("GENERAL", {}).get("MAX_WORKERS")
+            max_workers = self.config.get(YAMLSection.GENERAL, {}).get("MAX_WORKERS")
             with ProcessPoolExecutor(
                     max_workers=max_workers, initializer=initializer, initargs=initargs
             ) as executor:
@@ -335,46 +486,91 @@ class BuildExecutor:
             halt_build = False
             for status, result_data in results:
                 step_name = result_data.get('step_name', 'N/A')
+
+                # Capture timing if available
+                if 'elapsed_time' in result_data:
+                    step_timings[step_name] = result_data['elapsed_time']
+
                 if status == 'EXECUTED':
                     finished_count += 1
-                    logger.log(f"✅ Finished step '{step_name}' [{finished_count}/{total_to_run}]")
+                    logger.log(f"✅ Finished step '{step_name}' [{finished_count}/{total_to_run}]\n")
+                    if status_callback:
+                        status_callback("step", finished_count, total_to_run, "done")
                     self.build_state[result_data['output_path']] = {
                         "hashes": result_data['hashes'], "mtime": result_data['mtime']
                     }
                 elif status == 'FAILED':
                     halt_build = True
                     logger.log(f"🔺 Build failed for Step '{step_name}'")
+                    if status_callback:
+                        status_callback("step", finished_count, total_to_run, "error")
+
             if halt_build:
                 self.state_manager.save_state(self.build_state)
                 return False
+
         self.state_manager.save_state(self.build_state)
+
+        # --- TIMING REPORT ---
+        total_build_time = time.time() - build_start_time
+        self._print_timing_report(logger, step_timings, total_build_time)
+
         return True
 
     @staticmethod
     def _run_single_command(task: Tuple[str, Dict, str]) -> Tuple[str, Dict]:
-        """Runs a command and streams all output to the configured log ."""
+        """Runs a command and streams all output to the configured log."""
         logger = get_logger()
         step_name, command, update_text = task
         output_path = command['output']
 
-        logger.log(f"\n▶️  Running step '{step_name}': {update_text}")
-        logger.log(f"  [{step_name}]       {command['cmd_string']}")
+        # --- Helper for log truncation ---
+        def _truncate(text: str, limit: int = 400) -> str:
+            """Keeps the start and end of long strings."""
+            if len(text) <= limit:
+                return text
+
+            # Keep first 40% and last 40% of the limit
+            keep = int(limit * 0.4)
+            omitted_count = len(text) - (keep * 2)
+
+            # Formatting: Clear brackets with internal spacing
+            return f"{text[:keep]} [ ... {omitted_count} chars truncated ... ] {text[-keep:]}"
+
+        # Log the command (Truncated)
+        cmd_display = _truncate(command['cmd_string'])
+        logger.log(f"\n\n▶️  Running step '{step_name}': {update_text}")
+        logger.log(f"  [{step_name}]       {cmd_display}")
+
+        start_time = time.perf_counter()
 
         try:
             process = subprocess.Popen(
                 command['cmd_string'], shell=True, stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
                 text=True, encoding='utf-8', errors='replace'
             )
+
             for line in iter(process.stdout.readline, ''):
-                logger.log(f"  [{step_name}]       {line.strip()}")
+                clean_line = line.strip()
+                if clean_line:
+                    # Also truncate massive output lines (rare but possible with WKT echos)
+                    logger.log(f"  [{step_name}]       {_truncate(clean_line)}")
+
             return_code = process.wait()
+
+            end_time = time.perf_counter()
+            elapsed = end_time - start_time
+
             if return_code != 0:
                 raise subprocess.CalledProcessError(return_code, "")
 
             new_mtime = os.path.getmtime(output_path)
             result_data = {
-                'step_name': step_name, 'output_path': output_path, 'hashes': command['hashes'],
-                'mtime': new_mtime
+                'step_name': step_name,
+                'output_path': output_path,
+                'hashes': command['hashes'],
+                'mtime': new_mtime,
+                'elapsed_time': elapsed
             }
             return 'EXECUTED', result_data
         except Exception as e:
@@ -382,15 +578,46 @@ class BuildExecutor:
             result_data = {'step_name': step_name}
             return 'FAILED', result_data
 
+    def _print_timing_report(self, logger: BuildLogger, step_timings: Dict[str, float], total_time: float):
+        """Generates and logs the timing summary table."""
+        logger.log("\n🔵 Timing Report:")
+
+        # Sort by duration (Longest first)
+        sorted_steps = sorted(step_timings.items(), key=lambda item: item[1], reverse=True)
+
+        # Calculate "CPU Time" (Sum of all work) vs "Wall Time" (Real world time)
+        total_cpu_time = sum(step_timings.values())
+
+        for step_name, duration in sorted_steps:
+            # Percent of the Wall Clock time this step was active
+            percent = (duration / total_time) * 100 if total_time > 0 else 0
+
+            minutes = int(duration // 60)
+            seconds = duration % 60
+            if minutes > 0:
+                time_str = f"{minutes}:{seconds:05.2f}"
+            else:
+                time_str = f"{seconds:.2f}s"
+
+            logger.log(f"{step_name:<30} {percent:>5.1f}%   {time_str}")
+
+        t_min = int(total_time // 60)
+        t_sec = total_time % 60
+
+        # Calculate parallelism factor (e.g., 2.5x speedup)
+        speedup = total_cpu_time / total_time if total_time > 0 else 1.0
+
+        logger.log("-" * 50)
+        logger.log(f"Wall Time: {t_min}:{t_sec:05.2f}  Parallel Speedup: {speedup:.1f}x")
 
 class BuildReporter:
-    """Generates human-readable descriptions and diagrams of the workflow."""
+    """Generates human-readable description of the workflow."""
 
     def __init__(self, config: Dict):
         self.config = config
 
     def generate_mermaid_diagram(self, graph: nx.DiGraph) -> str:
-        """Creates a Mermaid graph syntax string for the workflow."""
+        """Creates a Mermaid graph for the workflow."""
         if not graph.nodes:
             return "graph TD;\n    Empty_Workflow[Workflow is empty];"
 
@@ -417,8 +644,9 @@ class BuildReporter:
     def describe_workflow(self, profile_name: str) -> str:
         """Generates a full Markdown report for the workflow."""
         import datetime
-        timestamp = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S")
-        project_name = self.config.get("GENERAL", {}).get("PROJECT_NAME", "LiteBuild Project")
+        timestamp = datetime.datetime.now().strftime("%Y-%m-%d %H:%M")
+        project_cfg = self.config.get(YAMLSection.PROJECT)
+        project_name = project_cfg.get("PROJECT_NAME", "LiteBuild Project")
 
         # 1. Generate the Plan to resolve all variables
         planner = BuildPlanner(self.config, {})
@@ -439,33 +667,51 @@ class BuildReporter:
             f"# {project_name} Pipeline Documentation",
             "",
             f"**Profile:** `{profile_name}`  ",
-            f"**Generated:** {timestamp}  ",
+            f"**Date:**     {timestamp}  ",
             f"**Target Output:** `{final_output}`",
             "",
             "---",
             ""
         ]
 
+        # --- OVERVIEW SECTION ---
+        # Checks for the  OVERVIEW key in the config
+
+        overview_text = project_cfg.get("OVERVIEW")
+        if overview_text:
+            lines.append("## Overview")
+            lines.append(overview_text.strip())
+            lines.append("")
+            lines.append("---")
+            lines.append("")
+
         # --- MERMAID DIAGRAM ---
-        lines.append("## Workflow Visualization")
+        lines.append("## Workflow  ")
         lines.append("```mermaid")
         lines.append(self.generate_mermaid_diagram(graph))
         lines.append("```")
         lines.append("")
 
         # --- STEP DETAIL ---
-        lines.append("## Step-by-Step Guide")
+        lines.append("## Detailed Steps")
 
         workflow_def = self.config.get("WORKFLOW", {})
 
         for node_name in build_order:
             cmd_data = plan.command_map[node_name]
             step_def = workflow_def.get(node_name, {})
-
-            description = step_def.get("DESCRIPTION", f"Executes rule: `{step_def.get('RULE', {}).get('NAME')}`")
+            rule_name = step_def.get('RULE', {}).get('NAME')
 
             lines.append(f"### {node_name}")
-            lines.append(f"_{description}_")
+
+            # ---  DESCRIPTION LOGIC ---
+            if "DESCRIPTION" in step_def:
+                # Use blockquote for user-defined descriptions (handles multi-line well)
+                lines.append(f"> {step_def['DESCRIPTION']}")
+            else:
+                # Fallback to technical description
+                lines.append(f"_Executes rule: `{rule_name}`_")
+
             lines.append("")
 
             # Inputs
@@ -488,7 +734,6 @@ class BuildReporter:
 
         return "\n".join(lines)
 
-
 class BuildStateManager:
     """Manages loading and saving the .build_state.json file."""
 
@@ -517,4 +762,4 @@ class BuildStateManager:
 # --- Worker initializer  accepts a logger object ---
 def setup_worker_logger(logger: BuildLogger):
     """Initializes the logger for a worker process."""
-    setup_logger(logger)
+    setup_logger(logger)

{litebuild-0.4.1 → litebuild-0.7}/LiteBuild/build_logger.py

@@ -1,7 +1,7 @@
 # build_logger.py
 
 from contextlib import nullcontext
-from enum import IntEnum # <-- ADDED
+from enum import IntEnum
 from pathlib import Path
 import sys
 from typing import Optional, Tuple, Callable, Any, Union, TextIO
@@ -47,7 +47,6 @@ class BuildLogger:
             self.log_file_handle = open(log_file, 'a', encoding='utf-8')
             self.lock = FileLock(log_file.with_suffix(".lock"))
 
-        # --- FIX: Duck typing check instead of strict isinstance(TextIO) ---
         elif hasattr(output, 'write') and hasattr(output, 'flush'):
             self.log_file_handle = output
             self.lock = nullcontext()