codex-core 0.2.2__tar.gz → 0.4.0__tar.gz

{codex_core-0.2.2 → codex_core-0.4.0}/CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2026-04-04
+
+### Added
+
+- **Quality Gate**: Declarative configuration support via `pyproject.toml` (`[tool.codex-check]`).
+- **Static Compiler**: Dependency-graph strategy for JS bundles (@provides/@depends parsing and resolution).
+- **Static Compiler**: New `compile_bundle` entry point for unified asset compilation.
+
+### Changed
+
+- **Quality Gate**: Refactored `BaseCheckRunner` to prioritize `pyproject.toml` over class attributes.
+- **Developer Tools**: Simplified `tools/dev/check.py` to a thin launcher.
+- **Documentation**: Updated architecture guides to promote declarative configuration.
+
+### Fixed
+
+- **Quality Gate**: Resolved line length issues and suppressed security warnings (Bandit B603) for internal subprocess calls.
+
 ## [0.2.2] - 2026-03-29
 
 ### Fixed

{codex_core-0.2.2 → codex_core-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-core
-Version: 0.2.2
+Version: 0.4.0
 Summary: Core utilities, schemas and settings for Codex WaaS toolkit
 Project-URL: Homepage, https://github.com/codexdlc/codex-core
 Project-URL: Documentation, https://codexdlc.github.io/codex-core/

{codex_core-0.2.2 → codex_core-0.4.0}/docs/en/architecture/platform/dev.md

@@ -40,22 +40,29 @@ python tools/dev/check.py --ci          # everything non-interactively (GitHub A
 
 ### Project switches
 
-Projects can keep the shared orchestration and declare their local policy with
-simple boolean attributes on `CheckRunner`:
+The preferred way to declare project-level quality gate policy is via `pyproject.toml` using the `[tool.codex-check]` section:
+
+```toml
+[tool.codex-check]
+project-name = "my-project"
+audit-flags = "--skip-editable"
+run-lint = true
+run-types = true
+run-security = true
+run-unit-tests = true
+run-integration-tests = false
+test-stages = ["unit", "integration"]
+prompt-test-stages = ["integration"]
+```
+
+Legacy support for class attributes in `CheckRunner` is still available for backwards compatibility:
 
 ```python
 class CheckRunner(BaseCheckRunner):
-    RUN_LINT = True
-    RUN_TYPES = True
-    RUN_SECURITY = True
-    RUN_EXTRA_CHECKS = True
     RUN_UNIT_TESTS = True
     RUN_INTEGRATION_TESTS = False
 ```
 
-This is the preferred extension point when a library does not need every stage.
-Use method overrides only when behavior itself must change.
-
 ### Usage in a project
 
 ```python
@@ -171,6 +178,29 @@ JS source files into bundles. No Node.js, no external packages required.
 }
 ```
 
+JS also supports a dependency-aware mode:
+
+```json
+{
+    "js": {
+        "app.js": {
+            "strategy": "dependency_graph",
+            "entry": ["app/entry.js"],
+            "roots": ["core", "widgets", "builders", "app"]
+        }
+    }
+}
+```
+
+In this mode the compiler reads metadata from JS files:
+
+```js
+/* @provides cabinet.widgets.client_lookup
+   @depends cabinet.core.dom, cabinet.core.events */
+```
+
+and builds the bundle order automatically. The old ordered-mode with an explicit source list remains fully supported.
+
 Old CSS-only format is supported for backwards compatibility:
 ```json
 { "base.css": "app.css" }

{codex_core-0.2.2 → codex_core-0.4.0}/docs/ru/architecture/platform/dev.md

@@ -40,22 +40,29 @@ python tools/dev/check.py --ci          # всё без промптов (GitHub
 
 ### Проектные переключатели
 
-Проект может оставить общую оркестрацию и задать свою локальную политику через
-булевы атрибуты в `CheckRunner`:
+Рекомендуемый способ задания проектной политики проверки качества — через секцию `[tool.codex-check]` в файле `pyproject.toml`:
+
+```toml
+[tool.codex-check]
+project-name = "my-project"
+audit-flags = "--skip-editable"
+run-lint = true
+run-types = true
+run-security = true
+run-unit-tests = true
+run-integration-tests = false
+test-stages = ["unit", "integration"]
+prompt-test-stages = ["integration"]
+```
+
+Поддержка атрибутов класса в `CheckRunner` сохранена для обратной совместимости:
 
 ```python
 class CheckRunner(BaseCheckRunner):
-    RUN_LINT = True
-    RUN_TYPES = True
-    RUN_SECURITY = True
-    RUN_EXTRA_CHECKS = True
     RUN_UNIT_TESTS = True
     RUN_INTEGRATION_TESTS = False
 ```
 
-Это основной способ настройки, когда библиотеке не нужны все этапы проверки.
-Переопределяйте методы только тогда, когда нужно менять само поведение.
-
 ### Использование в проекте
 
 ```python
@@ -171,6 +178,29 @@ gen = ProjectTreeGenerator(
 }
 ```
 
+Для JS также поддерживается dependency-aware режим:
+
+```json
+{
+    "js": {
+        "app.js": {
+            "strategy": "dependency_graph",
+            "entry": ["app/entry.js"],
+            "roots": ["core", "widgets", "builders", "app"]
+        }
+    }
+}
+```
+
+В этом режиме компилятор читает metadata из JS-файлов:
+
+```js
+/* @provides cabinet.widgets.client_lookup
+   @depends cabinet.core.dom, cabinet.core.events */
+```
+
+И строит итоговый порядок автоматически. Старый ordered-mode через явный список файлов остаётся полностью поддержанным.
+
 Старый формат только для CSS поддерживается для обратной совместимости:
 ```json
 { "base.css": "app.css" }

{codex_core-0.2.2 → codex_core-0.4.0}/pyproject.toml

@@ -110,3 +110,12 @@ exclude_lines = [
 [tool.bandit]
 exclude_dirs = ["tests"]
 skips = ["B602", "B605", "B607", "B404"]
+
+[tool.codex-check]
+project-name = "codex-core"
+audit-flags = "--skip-editable --ignore-vuln CVE-2026-4539"
+integration-requires = "Redis"
+test-stages = ["unit", "integration"]
+prompt-test-stages = ["integration"]
+test-paths = ["tests"]
+types-paths = ["src"]

{codex_core-0.2.2 → codex_core-0.4.0}/src/codex_core/common/__init__.py

@@ -1,6 +1,6 @@
 """Common utilities: logging, caching, phone normalization, text processing."""
 
-from .log_context import TaskLogContext
+from .log_context import TaskLogContext, clear_log_context, get_log_context, set_log_context
 from .loguru_setup import (
     InterceptHandler,
     LoggingSettingsProtocol,
@@ -12,6 +12,9 @@ from .text import clean_string, normalize_name, sanitize_for_sms, transliterate
 
 __all__ = [
     "TaskLogContext",
+    "clear_log_context",
+    "get_log_context",
+    "set_log_context",
     "InterceptHandler",
     "LoggingSettingsProtocol",
     "setup_logging",

{codex_core-0.2.2 → codex_core-0.4.0}/src/codex_core/common/log_context.py

@@ -1,29 +1,63 @@
-"""Structured logging context bound to a named task or worker.
+"""Structured logging context: per-request contextvars and per-task wrappers.
 
-Provides :class:`TaskLogContext` — a thin, stateful wrapper around
-``logging.Logger`` that automatically enriches every log record with
-a fixed set of structured fields (task name, worker name, arbitrary
-extras).
+Two complementary mechanisms:
 
-This module intentionally avoids any dependency on Loguru so that it
-works with any log sink: standard-library ``logging``, Loguru (via
-:class:`~codex_core.common.loguru_setup.InterceptHandler`), JSON
-formatters, ELK, or Loki.
+1. **contextvars-based context** — ``set_log_context`` / ``clear_log_context`` /
+   ``get_log_context``.  Designed for async request/task scoping: set fields once
+   at the start of a request or worker task, and every ``logger.*()`` call in that
+   async context automatically includes them via the Loguru patcher configured in
+   :func:`~codex_core.common.loguru_setup.setup_logging`.
 
-Example:
+2. **TaskLogContext** — a stateful wrapper around ``logging.Logger`` for code that
+   uses the standard library directly (see class docstring for details).
+
+Example (contextvars):
+    ```python
+    from codex_core.common.log_context import set_log_context, clear_log_context
+
+    set_log_context(request_id="abc-123", char_id=42)
+    logger.info("CombatMoveSubmitted")  # extra contains request_id, char_id
+    clear_log_context()
+    ```
+
+Example (TaskLogContext):
     ```python
     from codex_core.common.log_context import TaskLogContext
 
     log = TaskLogContext("send_booking_notification", worker="notification_worker")
     log.info("Processing appointment", extra={"appointment_id": 123})
-    # LogRecord contains: task="send_booking_notification",
-    #   worker="notification_worker", appointment_id=123
     ```
 """
 
+import contextvars
 import logging
 from typing import Any
 
+# ---------------------------------------------------------------------------
+# Async-safe contextvars log context
+# ---------------------------------------------------------------------------
+
+_log_context: contextvars.ContextVar[dict[str, Any]] = contextvars.ContextVar(
+    "log_context", default={}
+)
+
+
+def set_log_context(**kwargs: Any) -> None:
+    """Merge *kwargs* into the current async-local log context."""
+    current = _log_context.get().copy()
+    current.update(kwargs)
+    _log_context.set(current)
+
+
+def clear_log_context() -> None:
+    """Reset the async-local log context to empty."""
+    _log_context.set({})
+
+
+def get_log_context() -> dict[str, Any]:
+    """Return a shallow copy of the current async-local log context."""
+    return _log_context.get().copy()
+
 
 class TaskLogContext:
     """Structured logging adapter that binds context fields to every record.

codex_core-0.4.0/src/codex_core/common/loguru_setup.py

@@ -0,0 +1,307 @@
+"""Application-level Loguru configuration helpers (optional dependency).
+
+Provides opinionated, zero-boilerplate Loguru setup for codex_tools
+applications.  The codex_core *library* itself never calls these
+helpers; it uses the standard ``logging`` module exclusively so that
+consumers retain full control over their log infrastructure.
+
+**Dev mode** (``debug=True``): three sinks — colourised stdout, rotating
+plain-text ``debug.log``, and JSON ``errors.json``.
+
+**Prod mode** (``debug=False``): a single JSON-serialised stdout sink
+designed for ingestion by Grafana Alloy / Loki / ELK.  File sinks are
+omitted because container runtimes capture stdout natively.
+
+Both modes inject a **patcher** that enriches every log record with:
+
+- ``service`` — the service name passed to the setup function.
+- Any fields set via :func:`~codex_core.common.log_context.set_log_context`
+  (request_id, char_id, correlation_id, etc.).
+
+A built-in **healthcheck filter** suppresses records whose ``extra``
+contains ``healthcheck=True``, preventing ``/health`` endpoint noise
+from reaching log aggregators.
+
+Standard-library ``logging`` records are bridged via
+:class:`InterceptHandler` so that third-party libraries (SQLAlchemy,
+httpx, aiogram, etc.) are automatically captured by Loguru.
+
+Availability:
+    ``loguru`` is an **optional** dependency.  Both :func:`setup_logging`
+    and :func:`setup_universal_logging` raise :exc:`ImportError` with an
+    actionable message when ``loguru`` is not installed.
+"""
+
+import logging
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+
+from .log_context import get_log_context
+
+if TYPE_CHECKING:
+    from types import FrameType
+
+    from loguru import Logger
+
+logger: "Logger | None"
+try:
+    from loguru import logger as _loguru_logger
+except ImportError:
+    logger = None
+else:
+    logger = _loguru_logger
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_context_patcher(service_name: str) -> Any:
+    """Return a Loguru patcher that injects service name and contextvars."""
+
+    def _patcher(record: dict[str, Any]) -> None:
+        record["extra"]["service"] = service_name
+        record["extra"].update(get_log_context())
+
+    return _patcher
+
+
+def _healthcheck_filter(record: dict[str, Any]) -> bool:
+    """Suppress log records tagged with ``healthcheck=True``."""
+    return not record["extra"].get("healthcheck", False)
+
+
+# ---------------------------------------------------------------------------
+# InterceptHandler
+# ---------------------------------------------------------------------------
+
+
+class InterceptHandler(logging.Handler):
+    """Bridge standard-library ``logging`` records to the Loguru sink.
+
+    Install this handler on the root logger (or any named logger) to
+    forward all ``logging``-based records into Loguru transparently.
+    The handler resolves the correct call-stack depth so that Loguru
+    reports the *original* call site rather than the handler frame.
+
+    This class is stateless and thread-safe; a single instance may be
+    shared across all intercepted loggers.
+
+    Example:
+        ```python
+        import logging
+        from codex_core.common.loguru_setup import InterceptHandler
+
+        logging.basicConfig(handlers=[InterceptHandler()], level=0, force=True)
+        ```
+    """
+
+    def emit(self, record: logging.LogRecord) -> None:
+        if logger is None:
+            return
+
+        level: str | int
+        try:
+            level = logger.level(record.levelname).name
+        except ValueError:
+            level = record.levelno
+
+        frame: FrameType | None = logging.currentframe()
+        depth = 6
+        while frame and frame.f_code.co_filename == logging.__file__:
+            frame = frame.f_back
+            depth += 1
+
+        logger.opt(depth=depth, exception=record.exc_info).log(level, record.getMessage())
+
+
+# ---------------------------------------------------------------------------
+# setup_universal_logging (raw-args variant)
+# ---------------------------------------------------------------------------
+
+_CONSOLE_FORMAT = (
+    "<green>{time:YYYY-MM-DD HH:mm:ss}</green> | "
+    "<level>{level: <8}</level> | "
+    "<magenta>{extra[service]}</magenta> | "
+    "<cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> - "
+    "<level>{message}</level>"
+)
+
+_FILE_FORMAT = "{time:YYYY-MM-DD HH:mm:ss} | {level: <8} | {name}:{function}:{line} - {message}"
+
+
+def setup_universal_logging(
+    log_dir: Path,
+    service_name: str = "App",
+    console_level: str = "INFO",
+    file_level: str = "DEBUG",
+    rotation: str = "10 MB",
+    is_debug: bool = False,
+) -> None:
+    """Configure Loguru with three sinks and standard-library interception.
+
+    Intended for applications that do not use
+    :class:`~codex_core.settings.BaseCommonSettings` but still want the
+    full codex_core logging stack.  Callers supply raw configuration
+    values directly rather than a settings object.
+
+    Args:
+        log_dir: Directory where log files are created.
+        service_name: Label embedded in the console format string.
+        console_level: Minimum level for stdout output.
+        file_level: Minimum level for the debug log file.
+        rotation: Loguru rotation threshold string.
+        is_debug: When ``True``, enables ``backtrace`` and ``diagnose``.
+
+    Raises:
+        ImportError: If ``loguru`` is not installed.
+    """
+    if logger is None:
+        raise ImportError("loguru is not installed. Please install it manually: pip install loguru")
+
+    logger.remove()
+    log_dir.mkdir(parents=True, exist_ok=True)
+
+    logger.configure(patcher=_make_context_patcher(service_name))
+
+    logger.add(
+        sink=sys.stdout,
+        level=console_level,
+        colorize=True,
+        filter=_healthcheck_filter,
+        format=_CONSOLE_FORMAT,
+    )
+
+    logger.add(
+        sink=str(log_dir / "debug.log"),
+        level=file_level,
+        rotation=rotation,
+        compression="zip",
+        format=_FILE_FORMAT,
+        enqueue=True,
+        backtrace=is_debug,
+        diagnose=is_debug,
+    )
+
+    logger.add(
+        sink=str(log_dir / "errors.json"),
+        level="ERROR",
+        serialize=True,
+        rotation=rotation,
+        compression="zip",
+        enqueue=True,
+    )
+
+    logging.basicConfig(handlers=[InterceptHandler()], level=0, force=True)
+
+    logger.info("LoguruSetupComplete log_dir={}", log_dir)
+
+
+# ---------------------------------------------------------------------------
+# LoggingSettingsProtocol
+# ---------------------------------------------------------------------------
+
+
+@runtime_checkable
+class LoggingSettingsProtocol(Protocol):
+    """Structural protocol for the logging-related subset of settings."""
+
+    log_level_console: str
+    log_level_file: str
+    log_rotation: str
+    log_dir: str
+    debug: bool
+
+
+# ---------------------------------------------------------------------------
+# setup_logging (settings-based variant)
+# ---------------------------------------------------------------------------
+
+
+def setup_logging(
+    settings: LoggingSettingsProtocol,
+    service_name: str,
+    intercept_loggers: list[str] | None = None,
+    log_levels: dict[str, int] | None = None,
+) -> None:
+    """Configure Loguru from a settings object.
+
+    **Dev** (``settings.debug is True``): colourised console + file sinks.
+    **Prod** (``settings.debug is False``): JSON-serialised stdout only.
+
+    Both modes apply a patcher (service name + contextvars) and a
+    healthcheck filter.
+
+    Args:
+        settings: Object satisfying :class:`LoggingSettingsProtocol`.
+        service_name: Identifies the service in log output.
+        intercept_loggers: Logger names whose handlers are replaced
+            with :class:`InterceptHandler`.
+        log_levels: ``{logger_name: level_int}`` for silencing noisy
+            libraries.
+
+    Raises:
+        ImportError: If ``loguru`` is not installed.
+    """
+    if logger is None:
+        raise ImportError("loguru is not installed. Please install it manually: pip install loguru")
+
+    logger.remove()
+
+    logger.configure(patcher=_make_context_patcher(service_name))
+
+    if settings.debug:
+        # ── Dev: colourised console + file sinks ──
+        log_dir = Path(settings.log_dir) / service_name
+        log_dir.mkdir(parents=True, exist_ok=True)
+
+        logger.add(
+            sink=sys.stdout,
+            level=settings.log_level_console,
+            colorize=True,
+            filter=_healthcheck_filter,
+            format=_CONSOLE_FORMAT,
+        )
+
+        logger.add(
+            sink=str(log_dir / "debug.log"),
+            level=settings.log_level_file,
+            rotation=settings.log_rotation,
+            compression="zip",
+            format=_FILE_FORMAT,
+            enqueue=True,
+            backtrace=True,
+            diagnose=True,
+        )
+
+        logger.add(
+            sink=str(log_dir / "errors.json"),
+            level="ERROR",
+            serialize=True,
+            rotation=settings.log_rotation,
+            compression="zip",
+            enqueue=True,
+        )
+    else:
+        # ── Prod: JSON stdout only (Alloy / Loki / ELK ingestion) ──
+        logger.add(
+            sink=sys.stdout,
+            level=settings.log_level_console,
+            serialize=True,
+            colorize=False,
+            filter=_healthcheck_filter,
+            enqueue=True,
+        )
+
+    # Intercept standard logging
+    logging.basicConfig(handlers=[InterceptHandler()], level=0, force=True)
+
+    if intercept_loggers:
+        for name in intercept_loggers:
+            logging.getLogger(name).handlers = [InterceptHandler()]
+
+    if log_levels:
+        for name, level in log_levels.items():
+            logging.getLogger(name).setLevel(level)