Skip to content

architecture.md

Latest commit

 

History

History
114 lines (87 loc) · 4.78 KB

architecture.md

File metadata and controls

114 lines (87 loc) · 4.78 KB
Raw

Architecture Blueprint: crash_sight (Production-Grade Debugging Engine)

1. System Overview & Design Philosophy

crash_sight is a zero-dependency debugging engine for Python 3.8+ that operates at the runtime interceptor level. This system overrides the default sys.excepthook behavior to precisely extract the post-mortem state of a crashed application before the operating system terminates the process.

Core Principles:

  • Zero Dependencies: Utilizes only the Python Standard Library (sys, inspect, linecache, code, os, re, datetime, typing).
  • Data Integrity: Sanitizes sensitive data (PII/Credentials) at the in-memory snapshot level before it reaches the formatting layer.
  • Deterministic Isolation: State extraction must not modify the original objects residing in the application's memory heap.

2. System Workflow (Data Pipeline)

[Application Run] -> [Unhandled Exception Occurs] -> [sys.excepthook Intercepts] -> [Traceback Evaluator] -> [In-Memory State Extraction] -> [Security Masking Engine] -> [Console Formatter & Markdown Exporter] -> [Post-Mortem REPL Activation]

3. Component Specifications & Module Contracts

3.1. Core Interceptor (crash_sight.core.interceptor)

Responsible for global hook registration and stack frame traversal (stack frame windowing).

  • Registration Function:

    def install() -> None: ...

    Replaces sys.excepthook with a custom handler.

  • Stack Extraction Function (Frame Traversal):

  from types import TracebackType
  from typing import Tuple, Dict, Any, Type

  def extract_deepest_context(
      exctype: Type[BaseException], 
      value: BaseException, 
      tb: TracebackType
  ) -> Tuple[Dict[str, Any], Dict[str, Any], str, int, str]: ...
  • Logic: Iterates through while tb.tb_next: until reaching the deepest frame where the error originated.
  • Return: (f_locals, f_globals, filename, lineno, function_name).

3.2. Security Engine (crash_sight.security.masker)

A sensitive data cleansing engine based on string pattern matching (Pattern-Matching Data Scrubber).

  • Function Contract:
  from typing import Dict, Any

  def mask_environment(
      locals_dict: Dict[str, Any], 
      globals_dict: Dict[str, Any]
  ) -> Tuple[Dict[str, Any], Dict[str, Any]]: ...
  • Censorship Rules (Case-Insensitive Regex Match):
    • Target keywords: password, secret, token, apiKey, credential.
    • If a key is detected containing any of these substrings, its value is permanently replaced with the string literal: "******** (SECURED)".
    • Note: Must handle nested dictionaries if local variables are of JSON/Dict type.

3.3. Terminal Formatter (crash_sight.formatter.terminal)

A visual layout engine based on ANSI escape sequences for the CLI interface.

  • ANSI Code Definitions:

    RESET  = "\033[0m"
RED    = "\033[91m"
GREEN  = "\033[92m"
YELLOW = "\033[93m"
CYAN   = "\033[96m"

  • Function Contract:

    def generate_ansi_report(
    exctype_name: str,
    exc_message: str,
    filename: str,
    lineno: int,
    func_name: str,
    masked_locals: Dict[str, Any]
) -> str: ...
    • Logic Context: Uses linecache.getline(filename, current_lineno) to retrieve a code block with the range: [lineno - 2] to [lineno + 2]. The erroneous line must be prefixed with a visual indicator ---> in bright red color.

3.4. Post-Mortem REPL (crash_sight.repl.console)

Opens an interactive terminal session exactly at the memory coordinates where the application crashed.

  • Function Contract:
  def launch_interactive_shell(merged_context: Dict[str, Any]) -> None: ...
  • Logic: Utilizes code.InteractiveConsole(locals=merged_context). Merges masked_locals and masked_globals into a single namespace dictionary to be injected directly into the REPL session.
  • Banner Prompt: Explicitly displays an exit instruction to the developer.

3.5. Exporter Engine (crash_sight.exporter.markdown)

Writes a visualization identical to the terminal output into a static Markdown document format for team logging or CI/CD purposes.

  • Function Contract:
  def export_to_file(ansi_report: str, destination_dir: str = ".") -> str: ...
  • Logic: Strips ANSI color codes (re.sub(r'\x1b\[[0-9;]*m', '', ansi_report)) before writing to a file, ensuring the Markdown file is free of anomalous characters. The filename must follow the pattern crash_report_[YYYYMMDD_HHMMSS].md.

4. Data Type Definitions & Strict Constraints

All functions must include full type-hinting from the typing module. The use of the primitive Any data type is only permitted for object values within the f_locals and f_globals namespaces.