refactor(build): code analysis engine

changes:
  - file: configure.py
    area: config
    added: [_setup_stdlib_bridge, _wrap_sinks_with_env, _resolve_sinks, _wrap_sinks_with_llm, _read_env_config]
    modified: [configure]
  - file: decorators.py
    area: core
    removed: [_arg_types, _get_default_logger, decision_log, catch, decorator, log_call, +7 more]
  - file: _catch.py
    area: core
    added: [decorator, async_wrapper, catch, wrapper]
  - file: _core.py
    area: core
    added: [_module_of, _get_default_logger, _should_sample, set_default_logger, _arg_types]
  - file: _decision.py
    area: core
    added: [decision_log, async_wrapper, decorator, wrapper, _build_decision_extra]
  - file: _extract.py
    area: core
    added: [_maybe_extract]
  - file: _log_call.py
    area: core
    added: [async_wrapper, decorator, wrapper, log_call]
  - file: log_flow.py
    area: core
    added: [_extract_field, _first_present, _extract_trace_id]
    modified: [normalize_entry, LogFlowParser]

dependencies:
  flow: "_catch→_core, _log_call→_core, _decision→_core"
  - _catch.py -> _core.py
  - _catch.py -> _extract.py
  - _decision.py -> _core.py
  - _log_call.py -> _core.py
  - _log_call.py -> _extract.py

stats:
  lines: "+1177/-935 (net +242)"
  files: 16
  complexity: "Large structural change (normalized)"

Author: tom-sapletta-com

.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master, develop]
+  pull_request:
+    branches: [main, master]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e . || pip install -r requirements.txt || true
+
+      - name: Run tests
+        run: |
+          python -m pytest tests/ -v --tb=short
+
+      - name: Lint
+        run: |
+          pip install flake8 || true
+          flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics || true

CHANGELOG.md

@@ -1,3 +1,33 @@
+## [0.2.18] - 2026-03-02
+
+### Summary
+
+refactor(build): code analysis engine
+
+### Docs
+
+- docs: update README
+- docs: update context.md
+
+### Ci
+
+- config: update ci.yml
+
+### Other
+
+- update nfo/configure.py
+- update nfo/decorators.py
+- update nfo/decorators/__init__.py
+- update nfo/decorators/_catch.py
+- update nfo/decorators/_core.py
+- update nfo/decorators/_decision.py
+- update nfo/decorators/_extract.py
+- update nfo/decorators/_log_call.py
+- update nfo/log_flow.py
+- update project/analysis.toon
+- ... and 3 more
+
+
 ## [0.2.16] - 2026-02-18
 
 ### Summary

VERSION

@@ -1 +1 @@
-0.2.16
+0.2.18

nfo/__init__.py

@@ -125,7 +125,7 @@ def __getattr__(name: str):
         return FastAPIMiddleware
     raise AttributeError(f"module 'nfo' has no attribute {name!r}")
 
-__version__ = "0.2.17"
+__version__ = "0.2.18"
 
 __all__ = [
     "log_call",

nfo/configure.py

@@ -10,9 +10,7 @@
 
 import logging
 import os
-import sys
-from pathlib import Path
-from typing import Any, Dict, List, Optional, Sequence, Union
+from typing import Any, List, Optional, Sequence, Union
 
 from nfo.logger import Logger
 from nfo.sinks import CSVSink, MarkdownSink, SQLiteSink, Sink
@@ -117,6 +115,164 @@ def emit(self, record: logging.LogRecord) -> None:
                 pass
 
 
+def _read_env_config(
+    env_prefix: str,
+    level: str,
+    environment: Optional[str],
+    llm_model: Optional[str],
+    auto_extract_meta: bool,
+    meta_policy: Optional[Any],
+) -> tuple[str, Optional[str], Optional[str], bool, Optional[Any], Optional[str]]:
+    """Read environment variable overrides for configuration.
+    
+    Returns:
+        Tuple of (level, environment, llm_model, auto_extract_meta, meta_policy, env_sinks)
+    """
+    env_level = os.environ.get(f"{env_prefix}LEVEL")
+    if env_level:
+        level = env_level.upper()
+
+    env_env = os.environ.get(f"{env_prefix}ENV")
+    if env_env:
+        environment = env_env
+
+    env_llm = os.environ.get(f"{env_prefix}LLM_MODEL")
+    if env_llm:
+        llm_model = env_llm
+
+    env_meta_extract = os.environ.get(f"{env_prefix}META_EXTRACT", "").lower()
+    if env_meta_extract in ("true", "1", "yes"):
+        auto_extract_meta = True
+
+    env_meta_threshold = os.environ.get(f"{env_prefix}META_THRESHOLD")
+    if env_meta_threshold:
+        from nfo.meta import ThresholdPolicy
+        threshold = int(env_meta_threshold)
+        if meta_policy is None:
+            meta_policy = ThresholdPolicy(max_arg_bytes=threshold, max_return_bytes=threshold)
+        else:
+            meta_policy.max_arg_bytes = threshold
+            meta_policy.max_return_bytes = threshold
+
+    env_sinks = os.environ.get(f"{env_prefix}SINKS")
+
+    return level, environment, llm_model, auto_extract_meta, meta_policy, env_sinks
+
+
+def _resolve_sinks(
+    sinks: Optional[Sequence[Union[str, Sink]]],
+    env_sinks: Optional[str],
+) -> List[Sink]:
+    """Build sink list from explicit specs or environment variable."""
+    resolved: List[Sink] = []
+    
+    if sinks is not None:
+        for s in sinks:
+            if isinstance(s, str):
+                resolved.append(_parse_sink_spec(s))
+            else:
+                resolved.append(s)
+    elif env_sinks:
+        for spec in env_sinks.split(","):
+            spec = spec.strip()
+            if spec:
+                resolved.append(_parse_sink_spec(spec))
+    
+    return resolved
+
+
+def _wrap_sinks_with_llm(
+    sinks: List[Sink],
+    llm_model: Optional[str],
+    detect_injection: bool,
+) -> List[Sink]:
+    """Wrap sinks with LLM analysis if model specified or injection detection enabled."""
+    if not sinks:
+        return sinks
+        
+    if llm_model:
+        from nfo.llm import LLMSink
+        return [
+            LLMSink(
+                model=llm_model,
+                delegate=sink,
+                async_mode=True,
+                detect_injection=detect_injection,
+            )
+            for sink in sinks
+        ]
+    elif detect_injection:
+        from nfo.llm import LLMSink
+        return [
+            LLMSink(
+                model="",
+                delegate=sink,
+                async_mode=False,
+                detect_injection=True,
+                analyze_levels=[],
+            )
+            for sink in sinks
+        ]
+    
+    return sinks
+
+
+def _wrap_sinks_with_env(
+    sinks: List[Sink],
+    environment: Optional[str],
+    version: Optional[str],
+) -> List[Sink]:
+    """Wrap sinks with environment tagging if environment or version specified."""
+    if not sinks or not (environment or version):
+        return sinks
+        
+    from nfo.env import EnvTagger
+    return [
+        EnvTagger(
+            sink,
+            environment=environment,
+            version=version,
+            auto_detect=True,
+        )
+        for sink in sinks
+    ]
+
+
+def _setup_stdlib_bridge(
+    logger: Logger,
+    level: str,
+    resolved_sinks: List[Sink],
+    bridge_stdlib: bool,
+    modules: Optional[Sequence[str]],
+) -> None:
+    """Bridge stdlib loggers to nfo sinks (if sinks are configured)."""
+    if not resolved_sinks or not (bridge_stdlib or modules):
+        return
+        
+    bridge = _StdlibBridge(logger)
+    bridge.setLevel(getattr(logging, level.upper(), logging.DEBUG))
+
+    if bridge_stdlib:
+        root = logging.getLogger()
+        if bridge not in root.handlers:
+            root.addHandler(bridge)
+
+    if modules:
+        # Sort so parents come before children (shorter names first).
+        # Only attach bridge to a logger if no ancestor in the list
+        # already has it — stdlib propagation handles children.
+        bridged: set[str] = set()
+        for mod in sorted(modules, key=len):
+            has_ancestor = any(
+                mod.startswith(anc + ".") for anc in bridged
+            )
+            mod_logger = logging.getLogger(mod)
+            if not has_ancestor:
+                if bridge not in mod_logger.handlers:
+                    mod_logger.addHandler(bridge)
+                bridged.add(mod)
+
+
 def configure(
     *,
     name: str = "nfo",
@@ -204,90 +360,23 @@ def configure(
     if _configured and not force and _last_logger is not None:
         return _last_logger
 
-    # Environment overrides
-    env_level = os.environ.get(f"{env_prefix}LEVEL")
-    if env_level:
-        level = env_level.upper()
-
-    env_sinks = os.environ.get(f"{env_prefix}SINKS")
-
-    # Environment overrides for new features
-    env_env = os.environ.get(f"{env_prefix}ENV")
-    if env_env:
-        environment = env_env
-    env_llm = os.environ.get(f"{env_prefix}LLM_MODEL")
-    if env_llm:
-        llm_model = env_llm
-
-    # Meta extraction env overrides
-    env_meta_extract = os.environ.get(f"{env_prefix}META_EXTRACT", "").lower()
-    if env_meta_extract in ("true", "1", "yes"):
-        auto_extract_meta = True
-    env_meta_threshold = os.environ.get(f"{env_prefix}META_THRESHOLD")
-    if env_meta_threshold:
-        from nfo.meta import ThresholdPolicy
-        threshold = int(env_meta_threshold)
-        if meta_policy is None:
-            meta_policy = ThresholdPolicy(max_arg_bytes=threshold, max_return_bytes=threshold)
-        else:
-            meta_policy.max_arg_bytes = threshold
-            meta_policy.max_return_bytes = threshold
+    # Read environment overrides
+    level, environment, llm_model, auto_extract_meta, meta_policy, env_sinks = _read_env_config(
+        env_prefix, level, environment, llm_model, auto_extract_meta, meta_policy
+    )
 
     # Store global meta policy and auto_extract flag
     _global_meta_policy = meta_policy
     _global_auto_extract_meta = auto_extract_meta
 
     # Build sink list
-    resolved_sinks: List[Sink] = []
-    if sinks is not None:
-        for s in sinks:
-            if isinstance(s, str):
-                resolved_sinks.append(_parse_sink_spec(s))
-            else:
-                resolved_sinks.append(s)
-    elif env_sinks:
-        for spec in env_sinks.split(","):
-            spec = spec.strip()
-            if spec:
-                resolved_sinks.append(_parse_sink_spec(spec))
+    resolved_sinks = _resolve_sinks(sinks, env_sinks)
 
     # Wrap sinks with LLM analysis if model specified
-    if llm_model and resolved_sinks:
-        from nfo.llm import LLMSink
-        resolved_sinks = [
-            LLMSink(
-                model=llm_model,
-                delegate=sink,
-                async_mode=True,
-                detect_injection=detect_injection,
-            )
-            for sink in resolved_sinks
-        ]
-    elif detect_injection and resolved_sinks:
-        from nfo.llm import LLMSink
-        resolved_sinks = [
-            LLMSink(
-                model="",
-                delegate=sink,
-                async_mode=False,
-                detect_injection=True,
-                analyze_levels=[],
-            )
-            for sink in resolved_sinks
-        ]
+    resolved_sinks = _wrap_sinks_with_llm(resolved_sinks, llm_model, detect_injection)
 
     # Wrap sinks with env tagging if environment or version specified
-    if (environment or version) and resolved_sinks:
-        from nfo.env import EnvTagger
-        resolved_sinks = [
-            EnvTagger(
-                sink,
-                environment=environment,
-                version=version,
-                auto_detect=True,
-            )
-            for sink in resolved_sinks
-        ]
+    resolved_sinks = _wrap_sinks_with_env(resolved_sinks, environment, version)
 
     # Create logger
     logger = Logger(
@@ -298,30 +387,8 @@ def configure(
     )
     set_default_logger(logger)
 
-    # Bridge stdlib loggers to nfo sinks (if sinks are configured)
-    if resolved_sinks and (bridge_stdlib or modules):
-        bridge = _StdlibBridge(logger)
-        bridge.setLevel(getattr(logging, level.upper(), logging.DEBUG))
-
-        if bridge_stdlib:
-            root = logging.getLogger()
-            if bridge not in root.handlers:
-                root.addHandler(bridge)
-
-        if modules:
-            # Sort so parents come before children (shorter names first).
-            # Only attach bridge to a logger if no ancestor in the list
-            # already has it — stdlib propagation handles children.
-            bridged: set[str] = set()
-            for mod in sorted(modules, key=len):
-                has_ancestor = any(
-                    mod.startswith(anc + ".") for anc in bridged
-                )
-                mod_logger = logging.getLogger(mod)
-                if not has_ancestor:
-                    if bridge not in mod_logger.handlers:
-                        mod_logger.addHandler(bridge)
-                    bridged.add(mod)
+    # Bridge stdlib loggers to nfo sinks
+    _setup_stdlib_bridge(logger, level, resolved_sinks, bridge_stdlib, modules)
 
     _configured = True
     _last_logger = logger