whykit 0.3.1__py3-none-any.whl

whykit/completion.py

@@ -0,0 +1,193 @@
+"""Shell completion scripts generated from the argparse tree.
+
+The scripts are derived from ``build_parser()`` at print time, so a new
+subcommand or option completes the moment it exists; there is no second list
+to keep in sync. Bash output stays compatible with the Bash 3.2 that macOS
+still ships (no associative arrays), and zsh reuses it through bashcompinit.
+"""
+from __future__ import annotations
+
+import argparse
+from dataclasses import dataclass, field
+
+SHELLS = ("bash", "zsh", "fish")
+
+
+@dataclass
+class _Option:
+    flags: list[str]
+    help: str
+    takes_value: bool
+    choices: list[str]
+
+
+@dataclass
+class _Command:
+    path: tuple[str, ...]
+    help: str = ""
+    options: list[_Option] = field(default_factory=list)
+    arguments: list[str] = field(default_factory=list)  # positional choices
+    children: dict[str, _Command] = field(default_factory=dict)
+
+
+def _clean_help(text: str | None) -> str:
+    if not text or text == argparse.SUPPRESS:
+        return ""
+    return " ".join(text.replace("%(default)s", "").replace("(default: )", "").split())
+
+
+def _walk(parser: argparse.ArgumentParser, path: tuple[str, ...], help_text: str = "") -> _Command:
+    node = _Command(path=path, help=help_text)
+    for action in parser._actions:  # argparse has no public introspection API
+        if isinstance(action, argparse._SubParsersAction):
+            helps = {choice.dest: choice.help for choice in action._choices_actions}
+            for name, child in action.choices.items():
+                node.children[name] = _walk(child, (*path, name), _clean_help(helps.get(name)))
+        elif not action.option_strings:
+            node.arguments.extend(str(c) for c in action.choices or ())
+        else:
+            node.options.append(_Option(
+                flags=list(action.option_strings),
+                help=_clean_help(action.help),
+                takes_value=action.nargs != 0,
+                choices=[str(c) for c in action.choices] if action.choices else [],
+            ))
+    return node
+
+
+def _flatten(node: _Command) -> list[_Command]:
+    out = [node]
+    for child in node.children.values():
+        out.extend(_flatten(child))
+    return out
+
+
+def _bash(root: _Command) -> str:
+    nodes = _flatten(root)
+    words, choices = [], []
+    for node in nodes:
+        key = " ".join(node.path)
+        flags = [flag for opt in node.options for flag in opt.flags]
+        words.append(
+            f'    "{key}") subs="{" ".join(node.children)}"; args="{" ".join(node.arguments)}"; opts="{" ".join(flags)}" ;;'
+        )
+        for opt in node.options:
+            if opt.choices:
+                for flag in opt.flags:
+                    choices.append(f'    "{key}|{flag}") echo "{" ".join(opt.choices)}" ;;')
+            elif opt.takes_value:
+                for flag in opt.flags:
+                    choices.append(f'    "{key}|{flag}") echo "__value__" ;;')
+    return f"""# bash completion for whykit (generated by `whykit completion bash`)
+__whykit_words() {{
+  case "$1" in
+{chr(10).join(words)}
+    *) subs=""; args=""; opts="" ;;
+  esac
+}}
+
+__whykit_choices() {{
+  case "$1|$2" in
+{chr(10).join(choices)}
+  esac
+}}
+
+_whykit() {{
+  local cur="${{COMP_WORDS[COMP_CWORD]}}" prev="" path="" w i subs args opts values skip=0
+  [ "$COMP_CWORD" -gt 0 ] && prev="${{COMP_WORDS[COMP_CWORD-1]}}"
+  for ((i = 1; i < COMP_CWORD; i++)); do
+    w="${{COMP_WORDS[i]}}"
+    if [ "$skip" = 1 ]; then skip=0; continue; fi
+    case "$w" in
+      -*)
+        [ -n "$(__whykit_choices "$path" "$w")" ] && skip=1
+        continue ;;
+    esac
+    __whykit_words "$path"
+    case " $subs " in *" $w "*) path="${{path:+$path }}$w" ;; esac
+  done
+  COMPREPLY=()
+  values="$(__whykit_choices "$path" "$prev")"
+  if [ "$values" = "__value__" ]; then
+    return 0
+  elif [ -n "$values" ]; then
+    COMPREPLY=($(compgen -W "$values" -- "$cur"))
+    return 0
+  fi
+  __whykit_words "$path"
+  case "$cur" in
+    -*) COMPREPLY=($(compgen -W "$opts" -- "$cur")) ;;
+    *) [ -n "$subs$args" ] && COMPREPLY=($(compgen -W "$subs $args" -- "$cur")) ;;
+  esac
+  return 0
+}}
+
+complete -o default -o bashdefault -F _whykit whykit
+"""
+
+
+def _zsh(root: _Command) -> str:
+    return (
+        "#compdef whykit\n"
+        "# zsh completion for whykit (generated by `whykit completion zsh`)\n"
+        "(( $+functions[compdef] )) || { autoload -U +X compinit && compinit -i; }\n"
+        "autoload -U +X bashcompinit && bashcompinit\n"
+        + _bash(root).split("\n", 1)[1]
+    )
+
+
+def _fish_quote(text: str) -> str:
+    return "'" + text.replace("\\", "\\\\").replace("'", "\\'") + "'"
+
+
+def _fish(root: _Command) -> str:
+    lines = ["# fish completion for whykit (generated by `whykit completion fish`)"]
+    nodes = _flatten(root)
+    # A nested command name can also be a top-level one (`new evidence` vs
+    # `evidence`), so a depth-1 condition excludes the parents that own it.
+    owners: dict[str, list[str]] = {}
+    for node in nodes:
+        if len(node.path) == 2:
+            owners.setdefault(node.path[1], []).append(node.path[0])
+
+    def condition(node: _Command) -> str:
+        if not node.path:
+            return "__fish_use_subcommand"
+        parts = [f"__fish_seen_subcommand_from {name}" for name in node.path]
+        if len(node.path) == 1 and node.path[0] in owners:
+            parts.append("not __fish_seen_subcommand_from " + " ".join(owners[node.path[0]]))
+        if node.children:
+            parts.append("not __fish_seen_subcommand_from " + " ".join(node.children))
+        return "; and ".join(parts)
+
+    for node in nodes:
+        cond = _fish_quote(condition(node))
+        for name, child in node.children.items():
+            parent = "__fish_use_subcommand" if not node.path else condition(node)
+            lines.append(f"complete -c whykit -n {_fish_quote(parent)} -f -a {name} -d {_fish_quote(child.help)}")
+        if node.arguments:
+            lines.append(f"complete -c whykit -n {cond} -f -a {_fish_quote(' '.join(node.arguments))}")
+        for opt in node.options:
+            spec = []
+            for flag in opt.flags:
+                if flag.startswith("--"):
+                    spec.append(f"-l {flag[2:]}")
+                elif len(flag) == 2:
+                    spec.append(f"-s {flag[1:]}")
+            if opt.choices:
+                spec.append(f"-xa {_fish_quote(' '.join(opt.choices))}")
+            elif opt.takes_value:
+                spec.append("-r -F")
+            lines.append(f"complete -c whykit -n {cond} {' '.join(spec)} -d {_fish_quote(opt.help)}")
+    return "\n".join(lines) + "\n"
+
+
+def render_completion(parser: argparse.ArgumentParser, shell: str) -> str:
+    root = _walk(parser, ())
+    if shell == "bash":
+        return _bash(root)
+    if shell == "zsh":
+        return _zsh(root)
+    if shell == "fish":
+        return _fish(root)
+    raise ValueError(f"unsupported shell: {shell}")

whykit/config.py

@@ -0,0 +1,233 @@
+"""Repository-local WhyKit policy configuration.
+
+WhyKit intentionally has no user-global configuration.  A vault may optionally
+carry ``whykit.toml`` so the same checkout has the same defaults and CI gates on
+every machine and for every agent.
+"""
+from __future__ import annotations
+
+import copy
+import tomllib
+from pathlib import Path
+from typing import Any
+
+from .rule_policy import PolicyError, build_policy
+
+CONFIG_FILE = "whykit.toml"
+FORMAT_VERSION = 1
+
+DEFAULT_CONFIG: dict[str, Any] = {
+    "format_version": FORMAT_VERSION,
+    "evidence_access_age_days": {},
+    "defaults": {
+        "owner": "TODO",
+        "sensitivity": "internal",
+        "decision_review_days": 90,
+        "status_due_days": 30,
+        "require_hub_links": False,
+    },
+    "profiles": {
+        "local": {
+            "strict": False,
+            "orphans": True,
+            "secrets": True,
+            "require_git": False,
+            "require_clean_tree": False,
+            "require_configured": False,
+            "require_hub_links": False,
+            "history": "optional",
+        },
+        "ci": {
+            "strict": True,
+            "orphans": True,
+            "secrets": True,
+            "require_git": False,
+            "require_clean_tree": False,
+            "require_configured": False,
+            "require_hub_links": False,
+            "history": "optional",
+        },
+        "release": {
+            "strict": True,
+            "orphans": True,
+            "secrets": True,
+            "require_git": True,
+            "require_clean_tree": True,
+            "require_configured": True,
+            "require_hub_links": False,
+            "history": "required",
+        },
+    },
+}
+
+_ALLOWED_SENSITIVITY = {"public", "internal", "confidential", "restricted"}
+_ALLOWED_HISTORY = {"off", "optional", "required"}
+_TOP_LEVEL_KEYS = {
+    "format_version",
+    "evidence_access_age_days",
+    "defaults",
+    "profiles",
+    "rules",
+}
+_DEFAULT_KEYS = {
+    "owner",
+    "sensitivity",
+    "decision_review_days",
+    "status_due_days",
+    "require_hub_links",
+}
+_PROFILE_KEYS = {
+    "strict", "orphans", "secrets", "require_git", "require_clean_tree",
+    "require_configured", "require_hub_links", "history",
+}
+
+
+class ConfigError(ValueError):
+    pass
+
+
+def _merge(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
+    result = copy.deepcopy(base)
+    for key, value in override.items():
+        if isinstance(value, dict) and isinstance(result.get(key), dict):
+            result[key] = _merge(result[key], value)
+        else:
+            result[key] = value
+    return result
+
+
+def _validate(config: dict[str, Any]) -> None:
+    unknown_top = set(config) - _TOP_LEVEL_KEYS
+    if unknown_top:
+        raise ConfigError("unknown top-level keys: " + ", ".join(sorted(unknown_top)))
+
+    version = config.get("format_version")
+    if version != FORMAT_VERSION:
+        raise ConfigError(f"unsupported whykit.toml format_version: {version!r}; expected {FORMAT_VERSION}")
+
+    access_age = config.get("evidence_access_age_days")
+    if not isinstance(access_age, dict):
+        raise ConfigError("[evidence_access_age_days] must be a table")
+    for source_type, days in access_age.items():
+        if not isinstance(source_type, str) or not source_type.strip():
+            raise ConfigError("evidence_access_age_days source type must be non-empty")
+        if not isinstance(days, int) or isinstance(days, bool) or days < 0:
+            raise ConfigError(f"evidence_access_age_days.{source_type} must be an integer >= 0")
+
+    defaults = config.get("defaults")
+    if not isinstance(defaults, dict):
+        raise ConfigError("[defaults] must be a table")
+    unknown_defaults = set(defaults) - _DEFAULT_KEYS
+    if unknown_defaults:
+        raise ConfigError("unknown [defaults] keys: " + ", ".join(sorted(unknown_defaults)))
+    owner = defaults.get("owner")
+    if not isinstance(owner, str) or not owner.strip():
+        raise ConfigError("defaults.owner must be a non-empty string")
+    sensitivity = defaults.get("sensitivity")
+    if sensitivity not in _ALLOWED_SENSITIVITY:
+        raise ConfigError("defaults.sensitivity must be public, internal, confidential or restricted")
+    for key in ("decision_review_days", "status_due_days"):
+        value = defaults.get(key)
+        if not isinstance(value, int) or isinstance(value, bool) or value < 0:
+            raise ConfigError(f"defaults.{key} must be an integer >= 0")
+    if not isinstance(defaults.get("require_hub_links"), bool):
+        raise ConfigError("defaults.require_hub_links must be true or false")
+
+    profiles = config.get("profiles")
+    if not isinstance(profiles, dict) or not profiles:
+        raise ConfigError("[profiles] must define at least one profile")
+    for name, profile in profiles.items():
+        if not isinstance(name, str) or not name.strip() or not isinstance(profile, dict):
+            raise ConfigError("each profile must be a named table")
+        unknown = set(profile) - _PROFILE_KEYS
+        if unknown:
+            raise ConfigError(f"profile {name!r} has unknown keys: {', '.join(sorted(unknown))}")
+        for key in (
+            "strict", "orphans", "secrets", "require_git", "require_clean_tree",
+            "require_configured", "require_hub_links",
+        ):
+            if not isinstance(profile.get(key), bool):
+                raise ConfigError(f"profiles.{name}.{key} must be true or false")
+        if profile.get("history") not in _ALLOWED_HISTORY:
+            raise ConfigError(f"profiles.{name}.history must be off, optional or required")
+
+    # Team policy: [[rules.custom]] and [rules.overrides."<code>"]. Absent in
+    # the built-in defaults, so a vault without it reports exactly as before.
+    if "rules" in config:
+        try:
+            build_policy(config["rules"])
+        except PolicyError as exc:
+            raise ConfigError(str(exc)) from exc
+
+
+def load_config(root: Path) -> tuple[dict[str, Any], Path | None]:
+    """Load and validate repo-local config, falling back to deterministic defaults."""
+    path = root / CONFIG_FILE
+    if not path.exists():
+        config = copy.deepcopy(DEFAULT_CONFIG)
+        _validate(config)
+        return config, None
+    try:
+        text = path.read_text(encoding="utf-8-sig")
+    except (OSError, UnicodeDecodeError) as exc:
+        raise ConfigError(f"cannot read {CONFIG_FILE}: {exc}") from exc
+    return parse_config(text), path
+
+
+
+def parse_config(text: str) -> dict[str, Any]:
+    """Validate policy from a file or a pinned Git blob through the same path."""
+    try:
+        raw = tomllib.loads(text.removeprefix("\ufeff"))
+    except tomllib.TOMLDecodeError as exc:
+        raise ConfigError(f"cannot read {CONFIG_FILE}: {exc}") from exc
+    if not isinstance(raw, dict):
+        raise ConfigError(f"{CONFIG_FILE} must contain a TOML table")
+    unknown_raw_top = set(raw) - _TOP_LEVEL_KEYS
+    if unknown_raw_top:
+        raise ConfigError("unknown top-level keys: " + ", ".join(sorted(unknown_raw_top)))
+    if "defaults" in raw:
+        if not isinstance(raw["defaults"], dict):
+            raise ConfigError("[defaults] must be a table")
+        unknown_raw_defaults = set(raw["defaults"]) - _DEFAULT_KEYS
+        if unknown_raw_defaults:
+            raise ConfigError("unknown [defaults] keys: " + ", ".join(sorted(unknown_raw_defaults)))
+    config = _merge(DEFAULT_CONFIG, raw)
+    _validate(config)
+    return config
+
+
+def configuration_readiness(config: dict[str, Any], config_path: Path | None) -> tuple[bool, list[str]]:
+    """Return whether repository policy is concretely configured for release use.
+
+    This is intentionally stricter than syntactic validation: a generated policy
+    containing starter placeholders is valid TOML but is not an operational
+    release policy.
+    """
+    reasons: list[str] = []
+    if config_path is None:
+        reasons.append(f"{CONFIG_FILE} is missing; built-in defaults are not release configuration")
+    owner = str(config.get("defaults", {}).get("owner", "")).strip()
+    if owner.casefold() in {"todo", "tbd", "unknown", "unset", "n/a", "none"}:
+        reasons.append("defaults.owner is still a placeholder")
+    return not reasons, reasons
+
+
+def get_profile(config: dict[str, Any], name: str) -> dict[str, Any]:
+    profiles = config.get("profiles", {})
+    if name not in profiles:
+        raise ConfigError(f"unknown policy profile {name!r}; available: {', '.join(sorted(profiles))}")
+    return copy.deepcopy(profiles[name])
+
+
+def config_summary(root: Path) -> dict[str, Any]:
+    config, path = load_config(root)
+    source = "built-in defaults"
+    if path is not None:
+        source = path.resolve().relative_to(root.resolve()).as_posix()
+    return {
+        "contract_version": 1,
+        "source": source,
+        "configured": path is not None,
+        "config": config,
+    }

whykit/console.py

@@ -0,0 +1,217 @@
+"""Console output that survives terminals which cannot encode Unicode.
+
+Human messages use a few typographic glyphs (em dash, ellipsis, arrow) and
+echo vault content, which can be in any script. On an ASCII console
+(``LC_ALL=C``, ``PYTHONIOENCODING=ascii``) or a legacy Windows code page,
+Python's default ``strict`` stdout raises ``UnicodeEncodeError`` mid-report.
+
+Two rules keep output safe without changing what UTF-8 consumers receive:
+
+* Human text keeps the stream's encoding. Characters it cannot represent are
+  replaced: known glyphs by an ASCII spelling, anything else by a
+  backslash escape, so a path stays unambiguous rather than becoming ``?``.
+* Machine output (JSON, DOT, Mermaid) is always written as UTF-8, whatever
+  the console encoding. On a UTF-8 stream the bytes are unchanged; elsewhere
+  this is the only encoding a JSON consumer is required to accept (RFC 8259).
+"""
+
+from __future__ import annotations
+
+import codecs
+import json
+from contextlib import contextmanager
+from collections.abc import Iterator
+import re
+import sys
+from typing import Any, TextIO
+
+ERROR_HANDLER = "whykit-ascii-fallback"
+
+# Glyphs WhyKit itself prints, plus common typography that vault titles carry.
+ASCII_FALLBACKS: dict[str, str] = {
+    "—": "-",  # em dash
+    "–": "-",  # en dash
+    "−": "-",  # minus sign
+    "…": "...",
+    "→": "->",
+    "←": "<-",
+    "↔": "<->",
+    "‘": "'",
+    "’": "'",
+    "“": '"',
+    "”": '"',
+    " ": " ",
+    "•": "*",
+    "·": "-",
+    "✓": "OK",
+    "✗": "x",
+    "×": "x",
+    "≤": "<=",
+    "≥": ">=",
+    "≠": "!=",
+    "": "",
+}
+
+_DEFAULT_ERROR_MODES = frozenset({"strict", "backslashreplace", "surrogateescape"})
+_UTF_CODECS = frozenset({"utf-8", "utf-8-sig", "utf-16", "utf-16-le", "utf-16-be", "utf-32", "utf-32-le", "utf-32-be"})
+
+
+def _fallback(exc: UnicodeError) -> tuple[str | bytes, int]:
+    if not isinstance(exc, UnicodeEncodeError):
+        raise exc
+    chunk = exc.object[exc.start:exc.end]
+    if all(0xDC80 <= ord(char) <= 0xDCFF for char in chunk):
+        # A POSIX name that was not valid in the locale (C locale argv or file
+        # name). Usually the bytes are UTF-8: spell them like any other text so
+        # an ASCII console stays ASCII; bytes that are not UTF-8 become \xNN.
+        raw = bytes(ord(char) - 0xDC00 for char in chunk)
+        try:
+            chunk = raw.decode("utf-8")
+        except UnicodeDecodeError:
+            return "".join(f"\\x{byte:02x}" for byte in raw), exc.end
+    pieces = []
+    for char in chunk:
+        if char.isascii():
+            pieces.append(char)
+            continue
+        replacement = ASCII_FALLBACKS.get(char)
+        if replacement is None:
+            code = ord(char)
+            if code <= 0xFF:
+                replacement = f"\\x{code:02x}"
+            elif code <= 0xFFFF:
+                replacement = f"\\u{code:04x}"
+            else:
+                replacement = f"\\U{code:08x}"
+        pieces.append(replacement)
+    return "".join(pieces), exc.end
+
+
+try:
+    codecs.lookup_error(ERROR_HANDLER)
+except LookupError:
+    codecs.register_error(ERROR_HANDLER, _fallback)
+
+
+def _codec_name(stream: Any) -> str | None:
+    encoding = getattr(stream, "encoding", None)
+    if not encoding:
+        return None
+    try:
+        return codecs.lookup(encoding).name
+    except LookupError:
+        return None
+
+
+def is_utf(stream: Any) -> bool:
+    """True when ``stream`` encodes every code point (or its encoding is unknown)."""
+    name = _codec_name(stream)
+    return name is None or name in _UTF_CODECS
+
+
+def as_printed(text: str, stream: Any = None) -> str:
+    """*text* as ``stream`` (default stdout) will show it.
+
+    On a console that cannot encode every character the fallback handler
+    spells some of them as escapes, which changes how many columns the text
+    takes; layout code measures this form so tables stay aligned.
+    """
+    stream = sys.stdout if stream is None else stream
+    if is_utf(stream):
+        return text
+    encoding = _codec_name(stream)
+    assert encoding is not None
+    try:
+        return text.encode(encoding, getattr(stream, "errors", None) or "strict").decode(encoding, "replace")
+    except (UnicodeError, LookupError):
+        return text
+
+
+def harden_stream(stream: Any) -> None:
+    """Replace unencodable characters on a non-UTF stream instead of raising.
+
+    An explicit user choice such as ``PYTHONIOENCODING=ascii:replace`` is
+    respected: only the interpreter defaults (``strict`` on stdout,
+    ``backslashreplace`` on stderr, ``surrogateescape`` under the C/POSIX
+    locale) are swapped for the fallback handler, which keeps the
+    surrogateescape round-trip for undecodable file names.
+    """
+    reconfigure = getattr(stream, "reconfigure", None)
+    if reconfigure is None or is_utf(stream):
+        return
+    if getattr(stream, "errors", None) not in _DEFAULT_ERROR_MODES:
+        return
+    try:
+        reconfigure(errors=ERROR_HANDLER)
+    except (ValueError, OSError):  # pragma: no cover - closed or detached stream
+        return
+
+
+def harden_stdio() -> None:
+    harden_stream(sys.stdout)
+    harden_stream(sys.stderr)
+
+
+@contextmanager
+def _machine_stream(file: TextIO | None) -> Iterator[TextIO]:
+    stream = sys.stdout if file is None else file
+    reconfigure = getattr(stream, "reconfigure", None)
+    if reconfigure is None or is_utf(stream):
+        yield stream
+        return
+    encoding, errors = stream.encoding, stream.errors
+    stream.flush()
+    # surrogateescape turns C-locale argv/file-name surrogates back into the
+    # original (UTF-8) bytes, so the output matches a UTF-8 console byte for byte.
+    reconfigure(encoding="utf-8", errors="surrogateescape")
+    try:
+        yield stream
+        stream.flush()
+    finally:
+        reconfigure(encoding=encoding, errors=errors)
+
+
+def emit_machine(text: str, *, file: TextIO | None = None) -> None:
+    """Print machine-readable text as UTF-8, keeping newline translation."""
+    with _machine_stream(file) as stream:
+        print(text, file=stream)
+
+
+def emit_json(value: object, *, file: TextIO | None = None) -> None:
+    """Write the usual pretty JSON without building another complete string."""
+    with _machine_stream(file) as stream:
+        json.dump(value, stream, ensure_ascii=False, indent=2)
+        stream.write("\n")
+
+
+# Line breaks (including the Unicode ones), other control characters and the
+# bidirectional overrides. Printed raw, vault text containing them could start
+# a new log line that a CI runner reads as a command (``::error::``), move the
+# terminal cursor or recolour it (ESC), or reorder what a reviewer sees.
+# A raw string so the regex engine, not the source file, holds the control
+# characters: C0 except tab, DEL and C1, ALM, LRM/RLM, the Unicode line and
+# paragraph separators, and the bidi embeddings, overrides and isolates.
+_UNSAFE_DISPLAY_RE = re.compile(r"[\x00-\x08\x0a-\x1f\x7f-\x9f\u061c\u200e\u200f\u2028\u2029\u202a-\u202e\u2066-\u2069]")
+_DISPLAY_ESCAPES = {"\n": "\\n", "\r": "\\r"}
+
+
+def one_line(value: object) -> str:
+    """*value* as one inert line of human-readable output.
+
+    Vault text (titles, paths, finding messages) is untrusted. Every
+    character that could break the line or control the terminal is shown as a
+    visible escape instead; ordinary text, tabs and non-Latin scripts are
+    unchanged. Machine formats (JSON, SARIF, GitHub annotations) keep the
+    exact value and do their own escaping.
+    """
+    text = str(value)
+    if not _UNSAFE_DISPLAY_RE.search(text):
+        return text
+
+    def escape(match: re.Match[str]) -> str:
+        char = match.group(0)
+        code = ord(char)
+        return _DISPLAY_ESCAPES.get(char) or (f"\\x{code:02x}" if code <= 0xFF else f"\\u{code:04x}")
+
+    return _UNSAFE_DISPLAY_RE.sub(escape, text)
+