ecdat 0.2.0__py3-none-any.whl

ecdat/ui/art3d.py

@@ -0,0 +1,136 @@
+"""Pure ASCII 3D renderers — deterministic, dependency-free, unit-testable."""
+from __future__ import annotations
+
+import math
+
+Cell = tuple[str, int]        # (character, level) — level 0 means "empty"
+Frame = list[list[Cell]]      # frame[row][col]
+
+BLANK: Cell = (" ", 0)
+TORUS_CHARS = ".,-~:;=!*#$@"  # 12 shades, dark -> bright
+TORUS_LEVELS = len(TORUS_CHARS)
+GLOBE_LEVELS = 12
+HEX = "0123456789ABCDEF"
+
+
+def blank_frame(width: int, height: int) -> Frame:
+    return [[BLANK] * max(width, 0) for _ in range(max(height, 0))]
+
+
+def frame_to_rows(frame: Frame) -> list[str]:
+    return ["".join(ch for ch, _ in row) for row in frame]
+
+
+def render_torus(a: float, b: float, width: int, height: int, *,
+                 step_theta: float = 0.07, step_phi: float = 0.04) -> Frame:
+    """Classic spinning donut. a, b are rotation angles in radians."""
+    frame = blank_frame(width, height)
+    if width < 8 or height < 4:
+        return frame
+    r1, r2, k2 = 1.0, 2.0, 5.0
+    k1 = min(width, 2 * height) * k2 * 3.0 / (8.0 * (r1 + r2))
+    zbuf = [[0.0] * width for _ in range(height)]
+    ca, sa, cb, sb = math.cos(a), math.sin(a), math.cos(b), math.sin(b)
+    two_pi = 2.0 * math.pi
+    theta = 0.0
+    while theta < two_pi:
+        ct, st = math.cos(theta), math.sin(theta)
+        circle_x, circle_y = r2 + r1 * ct, r1 * st
+        phi = 0.0
+        while phi < two_pi:
+            cp, sp = math.cos(phi), math.sin(phi)
+            x = circle_x * (cb * cp + sa * sb * sp) - circle_y * ca * sb
+            y = circle_x * (sb * cp - sa * cb * sp) + circle_y * ca * cb
+            z = k2 + ca * circle_x * sp + circle_y * sa
+            ooz = 1.0 / z
+            xp = int(width / 2 + k1 * ooz * x)
+            yp = int(height / 2 - k1 * ooz * y * 0.5)      # 0.5 = terminal cell aspect ratio
+            if 0 <= xp < width and 0 <= yp < height and ooz > zbuf[yp][xp]:
+                lum = cp * ct * sb - ca * ct * sp - sa * st + cb * (ca * st - ct * sa * sp)
+                if lum > 0:
+                    idx = min(int(lum * 8), TORUS_LEVELS - 1)
+                    zbuf[yp][xp] = ooz
+                    frame[yp][xp] = (TORUS_CHARS[idx], idx + 1)
+            phi += step_phi
+        theta += step_theta
+    return frame
+
+
+def _star(col: int, row: int, t: float) -> Cell | None:
+    h = (col * 73856093) ^ (row * 19349663)
+    if h % 61 != 0:
+        return None
+    phase = (int(t * 2.5) + (h >> 7)) % 3
+    return (".", 1) if phase == 0 else (("+", 2) if phase == 1 else ("'", 1))
+
+
+def render_globe(t: float, width: int, height: int, *, ring: bool = True, stars: bool = True) -> Frame:
+    """A sphere whose surface is hex digits glued to it (they rotate with t), lit from the upper-left,
+    with a lat/long grid, an orbit ring precessing around it and three satellites."""
+    frame = blank_frame(width, height)
+    if width < 16 or height < 8:
+        return frame
+    cx, cy = (width - 1) / 2.0, (height - 1) / 2.0
+    rx = min(width / 2.8, height * 0.85)                   # sphere radius in x-cells; y radius = rx / 2
+    lx, ly, lz = -0.45, 0.55, 0.70
+    n = math.sqrt(lx * lx + ly * ly + lz * lz)
+    lx, ly, lz = lx / n, ly / n, lz / n
+    ct, st = math.cos(t), math.sin(t)
+    two_pi = 2.0 * math.pi
+    for row in range(height):
+        ny = -(row - cy) * 2.0 / rx
+        for col in range(width):
+            nx = (col - cx) / rx
+            d2 = nx * nx + ny * ny
+            if d2 > 1.0:
+                if stars:
+                    s = _star(col, row, t)
+                    if s:
+                        frame[row][col] = s
+                continue
+            nz = math.sqrt(1.0 - d2)
+            shade = 0.12 + 0.78 * max(0.0, nx * lx + ny * ly + nz * lz) + 0.25 * (1.0 - nz) ** 2
+            level = max(1, min(GLOBE_LEVELS, 1 + int(shade * (GLOBE_LEVELS - 1))))
+            sx = nx * ct - nz * st
+            sz = nx * st + nz * ct
+            lon = math.atan2(sx, sz)
+            lat = math.asin(max(-1.0, min(1.0, ny)))
+            qi = int((lon + math.pi) / two_pi * 96) % 96
+            qj = min(int((lat + math.pi / 2) / math.pi * 48), 47)
+            grid = qi % 12 == 0 or qj % 8 == 0
+            if level <= 2:
+                ch = "."
+            elif level <= 4:
+                ch = "+" if grid else ":"
+            else:
+                ch = HEX[(((qi * 73856093) ^ (qj * 19349663)) >> 3) % 16]
+            frame[row][col] = (ch, min(GLOBE_LEVELS, level + (1 if grid else 0)))
+    if ring:
+        cr, sr = math.cos(0.42), math.sin(0.42)            # ring tilt about X
+        yaw = t * 1.7 + 0.6
+        cyw, syw = math.cos(yaw), math.sin(yaw)            # ring precession about Y
+        rr = 1.28 * rx
+
+        def project(phi: float) -> tuple[int, int, bool]:
+            px, py, pz = math.cos(phi), 0.0, math.sin(phi)
+            py, pz = py * cr - pz * sr, py * sr + pz * cr
+            px, pz = px * cyw + pz * syw, -px * syw + pz * cyw
+            return int(round(cx + px * rr)), int(round(cy - py * rr / 2.0)), pz > 0
+
+        def visible(col: int, row: int, front: bool) -> bool:
+            if not (0 <= col < width and 0 <= row < height):
+                return False
+            if front:
+                return True
+            dx, dy = (col - cx) / rx, (row - cy) * 2.0 / rx
+            return dx * dx + dy * dy > 1.0                 # behind the globe: hidden where the disc covers it
+
+        for i in range(240):
+            col, row, front = project(two_pi * i / 240)
+            if visible(col, row, front):
+                frame[row][col] = ("o", GLOBE_LEVELS) if front else (".", 5)
+        for k in range(3):                                  # satellites
+            col, row, front = project(t * 2.2 + k * 2.0944)
+            if visible(col, row, front):
+                frame[row][col] = ("@", GLOBE_LEVELS)
+    return frame

ecdat/ui/art_static.py

@@ -0,0 +1,65 @@
+"""Static ASCII art for the results screens (pure, dependency-free). Every emblem is 9 rows x 19 cols."""
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+SAFE_LOCK = (
+    r'      .-"""-.      ',
+    r'     /  .-.  \     ',
+    r'     | |   | |     ',
+    r"   .-'-'---'-'-.   ",
+    r'   |   .---.   |   ',
+    r'   |   | o |   |   ',
+    r"   |   '-.-'   |   ",
+    r'   |     |     |   ',
+    r"   '-----------'   ",
+)
+WARN_LOCK = (
+    r'      .-"""-.      ',
+    r'     /  .-.  \     ',
+    r'     | |   | |     ',
+    r"   .-'-'---'-'-.   ",
+    r'   |   .-\-.   |   ',
+    r'   |   | ! |   |   ',
+    r"   |   '-/-'   |   ",
+    r'   |     |     |   ',
+    r"   '-----------'   ",
+)
+CRIT_LOCK = (
+    r'        .-"""-.    ',
+    r'       /  .-.  \   ',
+    r'       | |   |     ',
+    r"   .-'-'---'-'-.   ",
+    r'   |   .---.   |   ',
+    r'   |   | X |   |   ',
+    r"   |   '-.-'   |   ",
+    r'   |     |     |   ',
+    r"   '-----------'   ",
+)
+
+
+def verdict(counts: Mapping[str, int]) -> str:
+    """'crit' | 'warn' | 'safe' | 'empty' from a risk-level → count mapping."""
+    total = sum(counts.values())
+    if total == 0:
+        return "empty"
+    if counts.get("critical", 0) >= 1:
+        return "crit"
+    if counts.get("high", 0) + counts.get("medium", 0) >= 1:
+        return "warn"
+    return "safe"
+
+
+def emblem_for(v: str) -> tuple[str, ...]:
+    return {"crit": CRIT_LOCK, "warn": WARN_LOCK}.get(v, SAFE_LOCK)
+
+
+def headline_for(counts: Mapping[str, int], files: int = 0) -> str:
+    v = verdict(counts)
+    if v == "crit":
+        return f"{counts.get('critical', 0)} CRITICAL · {counts.get('high', 0)} HIGH — migrate before your next review"
+    if v == "warn":
+        return f"{counts.get('high', 0)} HIGH · {counts.get('medium', 0)} MEDIUM — plan your PQC migration"
+    if v == "safe":
+        return "Looking good — no urgent quantum exposure"
+    return f"No cryptographic artefacts detected in {files} files"

ecdat/ui/art_text.py

@@ -0,0 +1,81 @@
+"""Convert 3D frame data into gradient-coloured Rich Text.
+
+Consumes :class:`Frame` from :mod:`ecdat.ui.art3d` and produces
+:class:`~rich.text.Text` objects suitable for rendering.
+"""
+
+from __future__ import annotations
+
+from typing import Sequence
+
+from rich.style import Style
+from rich.text import Text
+
+from ecdat.ui.theme import MINT_GRADIENT
+
+Frame = Sequence[Sequence[tuple[str, int]]]
+
+
+def frame_to_text(
+    frame: Frame,
+    gradient: list[str] | None = None,
+) -> Text:
+    """Convert a :class:`Frame` into gradient-coloured :class:`~rich.text.Text`.
+
+    Level 0 cells map to a space with no style.  Level *n* (≥ 1) maps to
+    ``gradient[min(n, len(gradient)) - 1]``.  Consecutive cells at the same
+    level are merged into a single :class:`~rich.text.Text` run to keep the
+    output compact.
+
+    Args:
+        frame: A sequence of rows, each a sequence of ``(char, level)`` tuples.
+        gradient: Colour gradient (12 hex colours by default);
+                  defaults to :data:`~ecdat.ui.theme.MINT_GRADIENT`.
+
+    Returns:
+        A :class:`~rich.text.Text` ready for ``console.print()``.
+    """
+    if gradient is None:
+        gradient = MINT_GRADIENT
+    n_colors = len(gradient)
+
+    text = Text()
+    for ri, row in enumerate(frame):
+        if ri > 0:
+            text.append("\n")
+        if not row:
+            continue
+
+        # Run-length encode consecutive same-level cells.
+        prev_level = -1  # sentinel
+        run_chars: list[str] = []
+        for ch, level in row:
+            if level == prev_level:
+                run_chars.append(ch)
+                continue
+            # Flush previous run.
+            _flush_run(text, run_chars, prev_level, gradient, n_colors)
+            run_chars = [ch]
+            prev_level = level
+        _flush_run(text, run_chars, prev_level, gradient, n_colors)
+
+    return text
+
+
+def _flush_run(
+    text: Text,
+    chars: list[str],
+    level: int,
+    gradient: list[str],
+    n_colors: int,
+) -> None:
+    """Append a run of same-level characters to *text*."""
+    if not chars:
+        return
+    run_str = "".join(chars)
+    chars.clear()
+    if level <= 0:
+        text.append(run_str)  # blank — no style
+        return
+    color_idx = min(level, n_colors) - 1
+    text.append(run_str, style=Style(color=gradient[color_idx]))

ecdat/ui/banner.py

@@ -0,0 +1,148 @@
+r"""Gradient ASCII banner with optional shimmer highlight.
+
+The banner uses big Unicode box-drawing characters for modern terminals and
+falls back to pure ASCII for legacy environments.  Each column is coloured
+with a :data:`~ecdat.ui.theme.MINT_GRADIENT` gradient.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from rich.console import Group, RenderableType
+from rich.style import Style
+from rich.text import Text
+
+from ecdat.ui.theme import MINT_GRADIENT, PALETTE
+
+# ---------------------------------------------------------------------------
+# Banner ASCII art — raw strings for backslash safety
+# ---------------------------------------------------------------------------
+
+BANNER_LINES = (
+    r"███████╗ ██████╗██████╗  █████╗ ████████╗",
+    r"██╔════╝██╔════╝██╔══██╗██╔══██╗╚══██╔══╝",
+    r"█████╗  ██║     ██║  ██║███████║   ██║   ",
+    r"██╔══╝  ██║     ██║  ██║██╔══██║   ██║   ",
+    r"███████╗╚██████╗██████╔╝██║  ██║   ██║   ",
+    r"╚══════╝ ╚═════╝╚═════╝ ╚═╝  ╚═╝   ╚═╝   ",
+)
+
+BANNER_ASCII_LINES = (
+    r" _____   ____  ____      _     _____ ",
+    r"| ____| / ___||  _ \    / \   |_   _|",
+    r"|  _|  | |    | | | |  / _ \    | |  ",
+    r"| |___ | |___ | |_| | / ___ \   | |  ",
+    r"|_____| \____||____/ /_/   \_\  |_|  ",
+)
+
+TAGLINE = "Enterprise Cryptographic Discovery & Analysis Tool"
+SUBLINE = "post-quantum readiness \xb7 CBOM \xb7 Mosca"
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def banner_text(
+    *,
+    unicode: bool = True,
+    shimmer: Optional[float] = None,
+) -> Text:
+    """Return the ECDAT banner as a gradient-coloured :class:`~rich.text.Text`.
+
+    Each column is coloured from :data:`~ecdat.ui.theme.MINT_GRADIENT`, cycling
+    left-to-right across the full width of the banner text.
+
+    When *shimmer* is a float in ``[0, 1]``, the gradient is locally brightened
+    in a window of ±3 columns around ``shimmer * width`` — this produces a
+    "scanning highlight" effect when animated across frames.
+
+    Args:
+        unicode: Use the full box-drawing banner (``True``) or pure ASCII
+                 fallback (``False``).
+        shimmer: Optional highlight position ``0..1``; ``None`` disables.
+
+    Returns:
+        A single :class:`~rich.text.Text` with styled characters.
+    """
+    lines = BANNER_LINES if unicode else BANNER_ASCII_LINES
+    gradient = MINT_GRADIENT
+    n_colors = len(gradient)
+
+    # Determine max width for per-column gradient mapping.
+    max_width = max(len(line) for line in lines) if lines else 0
+
+    shimmer_col = -1
+    if shimmer is not None:
+        shimmer_col = int(round(max(0.0, min(1.0, shimmer)) * (max_width - 1)))
+        # Clamp shimmer window to valid column range.
+        shimmer_col = max(0, min(max_width - 1, shimmer_col))
+
+    text = Text()
+    for li, line in enumerate(lines):
+        if li > 0:
+            text.append("\n")
+        for ci, ch in enumerate(line):
+            # Base gradient index from column position.
+            if max_width > 1:
+                base_idx = ci * (n_colors - 1) // (max_width - 1)
+            else:
+                base_idx = 0
+
+            # Shimmer brightens ±3 columns around shimmer_col.
+            idx = base_idx
+            if shimmer is not None and abs(ci - shimmer_col) <= 3:
+                boost = max(0, 3 - abs(ci - shimmer_col))
+                idx = min(n_colors - 1, base_idx + boost)
+
+            color = gradient[idx]
+            text.append(ch, style=Style(color=color, bold=False))
+
+    return text
+
+
+def render_banner(
+    version: Optional[str] = None,
+    *,
+    unicode: bool = True,
+) -> Group:
+    """Return the full banner as a :class:`~rich.console.Group`.
+
+    Layout (centred)::
+
+        [gradient banner art]
+        TAGLINE
+        SUBLINE
+        version (e.g. "v0.2.0")
+
+    Args:
+        version: Optional version string to display below the subline.
+        unicode: Use box-drawing banner (``True``) or ASCII (``False``).
+
+    Returns:
+        A :class:`~rich.console.Group` ready for ``console.print()``.
+    """
+    elements: list[RenderableType] = []
+
+    # Banner art.
+    elements.append(banner_text(unicode=unicode))
+
+    # TAGLINE — centred, accent colour.
+    tagline = Text(TAGLINE, style=Style(color=PALETTE.accent, bold=True))
+    tagline.justify = "center"
+    elements.append(tagline)
+
+    # SUBLINE — centred, muted.
+    subline = Text(SUBLINE, style=Style(color=PALETTE.muted))
+    subline.justify = "center"
+    elements.append(subline)
+
+    # Version — centred, dimmed.
+    if version:
+        ver = Text(f"v{version}", style=Style(color=PALETTE.muted, dim=True))
+        ver.justify = "center"
+        elements.append(ver)
+
+    return Group(*elements)

ecdat/ui/console.py

@@ -0,0 +1,119 @@
+"""Console factory — the ONLY module allowed to create a Rich :class:`~rich.console.Console`.
+
+Every :class:`~rich.console.Console` goes through :func:`make_console` so that
+the palette theme, ``NO_COLOR``, ``FORCE_COLOR``, and terminal width are
+applied consistently.  Direct ``Console()`` calls elsewhere are banned.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from typing import Optional
+
+from rich.console import Console
+from rich.theme import Theme
+
+from ecdat.ui.theme import rich_theme
+
+
+def _ensure_utf8_streams() -> None:
+    """Reconfigure stdout/stderr to UTF-8 when possible.
+
+    On Windows the default code page rarely supports box-drawing characters.
+    When a stream has a ``.reconfigure`` method (Python 3.7+) and is not
+    already UTF-8, we switch it to ``"utf-8"`` with ``errors="replace"`` so
+    that Rich can render box-drawing characters without raising
+    :exc:`UnicodeEncodeError`.
+
+    Never raises — the reconfigure is best-effort.
+    """
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            reconf = getattr(stream, "reconfigure", None)
+            if reconf is None:
+                continue
+            current_enc = getattr(stream, "encoding", None)
+            if current_enc is not None and current_enc.lower() not in (
+                "utf-8",
+                "utf8",
+            ):
+                reconf(encoding="utf-8", errors="replace")
+        except Exception:
+            pass  # best-effort
+
+
+def make_console(
+    *,
+    stderr: bool = False,
+    no_color: Optional[bool] = None,
+    width: Optional[int] = None,
+) -> Console:
+    """Create a themed :class:`~rich.console.Console`.
+
+    Callers outside ``ecdat/ui/`` use this factory; never construct a
+    ``Console`` directly.
+
+    Args:
+        stderr: Write to stderr instead of stdout (default: stdout).
+        no_color: Force colour off (``True``), on (``False``), or auto-detect
+                  (``None`` / omitted).  Respects the ``NO_COLOR`` and
+                  ``FORCE_COLOR`` env vars when *no_color* is ``None``.
+        width: Terminal width in cells; ``None`` auto-detects.
+
+    Returns:
+        A configured :class:`~rich.console.Console`.
+    """
+    _ensure_utf8_streams()
+
+    # Resolve no_color: explicit arg > NO_COLOR/FORCE_COLOR > auto-detect.
+    if no_color is None:
+        force = os.environ.get("FORCE_COLOR", "").strip()
+        if force == "0" or os.environ.get("NO_COLOR", "").strip():
+            no_color = True
+        elif force and force != "0":
+            no_color = False
+
+    # Build colour system and no_color flags.
+    if no_color is True:
+        color_system = None
+        _no_color = True
+    elif no_color is False:
+        color_system = "256"
+        _no_color = False
+    else:
+        color_system = "auto"
+        _no_color = None  # let Rich auto-detect
+
+    theme: Optional[Theme]
+    if _no_color is True:
+        theme = None
+    else:
+        theme = rich_theme()
+
+    return Console(
+        file=sys.stderr if stderr else sys.stdout,
+        theme=theme,
+        color_system=color_system,
+        no_color=_no_color,
+        width=width,
+        highlight=False,
+    )
+
+
+def is_interactive() -> bool:
+    """Return ``True`` when stdout is connected to an interactive terminal.
+
+    Delegates to Rich's :func:`~rich.console.detect_legacy_windows` and
+    ``sys.stdout.isatty()``.  Returns ``False`` in CI or when piped.
+    """
+    return sys.stdout.isatty()
+
+
+def supports_unicode(console: Console) -> bool:
+    """Return ``True`` when the console's encoding supports Unicode box-drawing.
+
+    This is almost always ``True`` on modern terminals (including Windows
+    Terminal).  Falls back to ``False`` for legacy Windows consoles.
+    """
+    return console.legacy_windows is False or console.encoding == "utf-8"

ecdat/ui/motion.py

@@ -0,0 +1,64 @@
+"""Motion / animation policy — respects reduced-motion, CI, and env overrides.
+
+Exports a single function: :func:`animations_enabled`.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+
+def animations_enabled(
+    reduce_motion: bool = False,
+    env: Optional[dict[str, str]] = None,
+) -> bool:
+    """Return ``True`` when animations should play.
+
+    Resolution order (first match wins):
+
+    1. ``ECDAT_ANIM`` env var — ``"0"``/``"off"``/``"false"``/``"no"`` →
+       ``False``; ``"1"``/``"on"``/``"true"``/``"yes"`` → ``True``.
+    2. If *reduce_motion* is ``True`` → ``False``.
+    3. If running under CI (``CI`` env var set to anything truthy) → ``False``.
+    4. If running under pytest (``PYTEST_CURRENT_TEST`` set) → ``False``.
+    5. If ``TERM`` is ``"dumb"`` → ``False``.
+    6. Otherwise → ``True`` (default: animations on).
+
+    Args:
+        reduce_motion: Caller-level reduced-motion flag (e.g. from
+                       ``prefers-reduced-motion``).
+        env: Environment dict; defaults to :data:`os.environ`.
+
+    Returns:
+        ``True`` if animations should play.
+    """
+    if env is None:
+        env = os.environ
+
+    # 1. Explicit override via ECDAT_ANIM.
+    anim = env.get("ECDAT_ANIM", "").strip().lower()
+    if anim:
+        if anim in ("0", "off", "false", "no"):
+            return False
+        if anim in ("1", "on", "true", "yes"):
+            return True
+
+    # 2. Reduced-motion flag.
+    if reduce_motion:
+        return False
+
+    # 3. CI environment.
+    if env.get("CI", "").strip():
+        return False
+
+    # 4. Pytest.
+    if env.get("PYTEST_CURRENT_TEST", "").strip():
+        return False
+
+    # 5. Dumb terminal.
+    if env.get("TERM", "").strip().lower() == "dumb":
+        return False
+
+    # 6. Default: animations on.
+    return True