update: config loadier and logging

Author: Yiannis128

CLAUDE.md

@@ -8,10 +8,26 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 - **Hatch** as the build system and project manager
 - **Python 3.12+** as the minimum required version
 - **pydantic-settings** for configuration management
+- **structlog** for structured logging
 - **AGPL-3.0** license
 
 ## Development Commands
 
+### Running the Application
+```bash
+# Run with hatch (preferred method)
+hatch run compile-flags [options]
+
+# Examples:
+hatch run compile-flags --help
+hatch run compile-flags -v              # INFO level logging
+hatch run compile-flags -vv             # DEBUG level logging
+hatch run compile-flags -vv -l rust -b /path/to/build
+
+# Run directly via Python module
+hatch run python -m compile_flags [options]
+```
+
 ### Package Management
 ```bash
 # Install in development mode
@@ -21,15 +37,6 @@ hatch shell
 hatch build
 ```
 
-### Testing
-```bash
-# Run tests (when test framework is added)
-hatch test
-
-# Run tests with coverage
-hatch test --cover
-```
-
 ### Type Checking
 ```bash
 # Run mypy type checker
@@ -39,19 +46,46 @@ hatch run types:check
 hatch run types:check compile_flags/module.py
 ```
 
-## Project Structure
+## Architecture
+
+### Configuration System
+The application uses a hybrid approach combining **argparse** for CLI parsing with **Pydantic Settings** for configuration management:
+
+1. **CLI Parsing (`__main__.py`)**: Uses argparse with `action="count"` to support `-v`, `-vv`, `-vvv` verbosity levels
+2. **Configuration Model (`config.py`)**: Pydantic `BaseSettings` model that:
+   - Validates all configuration values with type safety
+   - Uses `@model_validator` to compute `log_level` from `verbose` count
+   - Integrates with `CliApp.run()` pattern via `CliSettingsSource`
+
+### Logging System
+- **structlog** for structured logging with colored console output
+- Log levels mapped from verbosity: 0=WARNING, 1=INFO, 2+=DEBUG
+- Configuration in `config.py:configure_logging()`
+- All log messages include structured key-value pairs for better debugging
+
+### Entry Point Flow
+```
+__main__.py:parse_args()
+  → CliApp.run(Config, cli_settings_source=...)
+  → config.py:compute_log_level() (model_validator)
+  → __main__.py:configure_logging()
+  → Application logic with structured logging
+```
+
+## Code Style
 
-- `compile_flags/` - Main package source code
-  - `__about__.py` - Version information
-  - `__init__.py` - Package initialization
-- `tests/` - Test suite (pytest-based)
-- `pyproject.toml` - Project configuration and dependencies
+- Use modern Python type hints: `dict` not `Dict`, `| None` not `Optional`
+- Type annotate everything: variables, function arguments, and return types
+- All source files must include SPDX license headers (MIT for code files)
+- Version is managed in `compile_flags/__about__.py`
 
 ## Important Notes
 
-- The project uses modern Python type hints (e.g., `dict` instead of `Dict`, `| None` instead of `Optional`)
-- Version is managed in `compile_flags/__about__.py` (note: pyproject.toml incorrectly references `src/compile_flags/__about__.py`)
-- Coverage configuration excludes `__about__.py` from coverage reports
-- All source files include SPDX license headers (MIT for code files)
-- Use modern Python annotations, for example, use "| None" instead of "Optional".
-- Type annotate everything, including variables, function arguments, and function returns.
+- The hatch script at `pyproject.toml:39` uses `{args}` to pass CLI arguments through
+- When adding CLI arguments, update both `parse_args()` in `__main__.py` and the corresponding field in `Config` model
+- The `Config` model has `case_sensitive=False` for environment variable support
+- Environment variables can override defaults using `COMPILE_FLAGS_` prefix
+- Use modern Python type hints: `dict` not `Dict`, `| None` not `Optional`
+- Type annotate everything: variables, function arguments, and return types
+- All source files must include SPDX license headers (AGPL-3.0 for source files)
+- Version is managed in `compile_flags/__about__.py`

compile_flags/__about__.py

@@ -1,4 +1,4 @@
 # SPDX-FileCopyrightText: 2025-present Yiannis Charalambous <yiannis128@hotmail.com>
 #
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: AGPL-3.0
 __version__ = "0.0.1"

compile_flags/__init__.py

@@ -1,3 +1,3 @@
 # SPDX-FileCopyrightText: 2025-present Yiannis Charalambous <yiannis128@hotmail.com>
 #
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: AGPL-3.0

compile_flags/__main__.py

@@ -1,10 +1,77 @@
 # SPDX-FileCopyrightText: 2025-present Yiannis Charalambous <yiannis128@hotmail.com>
 #
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: AGPL-3.0
+
+import argparse
+import logging
+import sys
+
+import structlog
+from pydantic_settings import CliApp, CliSettingsSource
+
+from compile_flags.config import Config, configure_logging
+
+
+def create_parser() -> argparse.ArgumentParser:
+    """Create argparse parser with custom arguments."""
+    parser: argparse.ArgumentParser = argparse.ArgumentParser(
+        prog="compile-flags",
+        description="Multi-language compilation flags detector tool",
+    )
+
+    # Only add custom arguments that need special handling
+    # CliSettingsSource will automatically add all other Config fields
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        action="count",
+        default=0,
+        help="Increase verbosity (use -v for INFO, -vv for DEBUG, -vvv for maximum verbosity)",
+    )
+
+    return parser
 
 
 def main() -> None:
-    print("hello world")
+    """Main entry point for compile-flags CLI."""
+    # Create parser with custom arguments
+    parser: argparse.ArgumentParser = create_parser()
+
+    # Parse verbose level before Pydantic CLI parsing
+    args, _ = parser.parse_known_args()
+    verbose: int = args.verbose if hasattr(args, "verbose") else 0
+
+    # Map verbose count to log level
+    if verbose == 0:
+        log_level = logging.WARNING
+    elif verbose == 1:
+        log_level = logging.INFO
+    else:  # 2+
+        log_level = logging.DEBUG
+
+    # Configure logging before loading config, will also update in the config.
+    configure_logging(log_level)
+
+    # Create custom CLI settings source using our argparse parser
+    # This will automatically add all non-excluded Config fields to the parser
+    cli_settings: CliSettingsSource = CliSettingsSource(
+        Config,
+        cli_parse_args=True,
+        root_parser=parser,
+        cli_implicit_flags=True,
+    )
+
+    # Use CliApp.run with custom CLI settings source
+    config: Config = CliApp.run(Config, cli_settings_source=cli_settings)
+
+    # Get structured logger
+    log: structlog.stdlib.BoundLogger = structlog.get_logger()
+
+    # Log configuration
+    log.debug("Configuration loaded", **config.model_dump(mode="python"))
+    log.info("Starting compilation flags detection", build_dir=config.build_dir)
+
+    print("TODO")
 
 
 if __name__ == "__main__":

compile_flags/config.py

@@ -0,0 +1,98 @@
+# SPDX-FileCopyrightText: 2025-present Yiannis Charalambous <yiannis128@hotmail.com>
+#
+# SPDX-License-Identifier: AGPL-3.0
+
+import logging
+import sys
+
+import structlog
+from pydantic import AliasChoices, Field, PrivateAttr, computed_field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+def _alias_choice(value: str) -> AliasChoices:
+    """
+    Create aliases for config fields to work with multiple sources.
+
+    Args:
+        value: The field name
+
+    Returns:
+        AliasChoices with field name, dashed version, and env var version
+    """
+    return AliasChoices(
+        value,  # exact field name for direct matching
+        value.replace("_", "-"),  # dashed alias for CLI
+        f"COMPILE_FLAGS_{value.replace('-', '_').upper()}",  # prefixed env var alias
+    )
+
+
+def configure_logging(log_level: int) -> None:
+    """
+    Configure structlog with appropriate processors and log level.
+
+    Args:
+        log_level: The logging level to use
+    """
+    # Configure standard library logging
+    logging.basicConfig(
+        format="%(message)s",
+        level=log_level,
+        stream=sys.stdout,
+    )
+
+    # Configure structlog
+    structlog.configure(
+        processors=[
+            structlog.contextvars.merge_contextvars,
+            structlog.processors.add_log_level,
+            structlog.processors.StackInfoRenderer(),
+            structlog.dev.set_exc_info,
+            structlog.processors.TimeStamper(fmt="%Y-%m-%d %H:%M:%S", utc=False),
+            structlog.dev.ConsoleRenderer(colors=True),
+        ],
+        wrapper_class=structlog.make_filtering_bound_logger(log_level),
+        context_class=dict,
+        logger_factory=structlog.PrintLoggerFactory(),
+        cache_logger_on_first_use=False,
+    )
+
+
+class Config(BaseSettings):
+    """Configuration for compile-flags tool."""
+
+    # override from BaseSettings
+    model_config = SettingsConfigDict(
+        case_sensitive=False,
+        cli_parse_args=True,
+    )
+
+    output_file: str | None = Field(
+        default=None,
+        validation_alias=_alias_choice("output_file"),
+        description="Output file path for compilation flags",
+    )
+
+    language: str | None = Field(
+        default=None,
+        validation_alias=_alias_choice("language"),
+        description="Programming language to detect flags for (e.g., c, cpp, rust)",
+    )
+
+    build_dir: str = Field(
+        default=".",
+        validation_alias=_alias_choice("build_dir"),
+        description="Build directory to analyze",
+    )
+
+    @computed_field
+    @property
+    def log_level(self) -> int:
+        """The current log level."""
+        return logging.getLogger().getEffectiveLevel()
+
+    @computed_field
+    @property
+    def log_level_name(self) -> str:
+        """The current log level name."""
+        return logging.getLevelName(self.log_level)

pyproject.toml

@@ -21,6 +21,7 @@ classifiers = [
 ]
 dependencies = [
   "pydantic-settings",
+  "structlog",
 ]
 
 [project.scripts]
@@ -35,7 +36,7 @@ Source = "https://github.com/esbmc/compile-flags"
 path = "compile_flags/__about__.py"
 
 [tool.hatch.envs.default.scripts]
-compile-flags = "python -m compile_flags"
+compile-flags = "python -m compile_flags {args}"
 
 [tool.hatch.envs.types]
 extra-dependencies = [

tests/__init__.py

@@ -1,3 +1,3 @@
 # SPDX-FileCopyrightText: 2025-present Yiannis Charalambous <yiannis128@hotmail.com>
 #
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: AGPL-3.0