shipwright-kit 0.6.0__tar.gz

shipwright_kit-0.6.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Christian Huhn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

shipwright_kit-0.6.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: shipwright-kit
+Version: 0.6.0
+Summary: Shipwright — AI-agent dev framework + import-light design/eval/security library
+Author: Christian Huhn
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/duathron/shipwright
+Project-URL: Repository, https://github.com/duathron/shipwright
+Project-URL: Documentation, https://github.com/duathron/shipwright/blob/main/docs/library.md
+Project-URL: Changelog, https://github.com/duathron/shipwright/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/duathron/shipwright/issues
+Keywords: ci,dev-tooling,eval,design-tokens,severity,quality-gates
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: rich
+Requires-Dist: rich>=13.7; extra == "rich"
+Provides-Extra: banner
+Requires-Dist: pyfiglet>=1.0; extra == "banner"
+Dynamic: license-file
+
+# Shipwright
+
+![CI](https://github.com/duathron/shipwright/actions/workflows/ci.yml/badge.svg)
+![CodeQL](https://github.com/duathron/shipwright/actions/workflows/codeql.yml/badge.svg)
+![Coverage](https://img.shields.io/badge/coverage-%E2%89%A590%25-brightgreen.svg)
+![Types](https://img.shields.io/badge/types-mypy-blue.svg)
+![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)
+![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)
+
+Shipwright is two things that share one repo:
+
+- an installable, **import-light Python library** of shared dev-tooling runtime —
+  `shipwright_kit.design` (severity tiers + accessible output), `shipwright_kit.eval`
+  (detection-quality eval harness), `shipwright_kit.security` (a security pack);
+- an **AI-agent-operated development framework** — reusable CI/CD, a Copier
+  scaffolder, quality gates, and bundled agent skills + personas — that **dogfoods**
+  the library and the gates it hands to the projects built with it.
+
+The library is consumed today by two real tools: **barb** and **sift** both import
+`shipwright_kit.eval` to run their detection-quality gates.
+
+## Install
+
+The library is **not on PyPI** — the bare name `shipwright` belongs to an unrelated
+project, so the published distribution is **`shipwright-kit`** and the import name is
+**`shipwright_kit`**. For now, install from git:
+
+```bash
+uv pip install "git+https://github.com/duathron/shipwright@main"
+# then: import shipwright_kit
+```
+
+> [!NOTE]
+> Pin a release tag instead of `@main` for reproducible builds once a tagged
+> release of the `shipwright-kit` distribution is cut. Do **not** `pip install
+> shipwright` from PyPI — that is a different, unrelated package.
+
+The security pack needs no extra — it ships with the base install and registers
+through the `shipwright_kit.packs` entry point.
+
+## Library quickstart
+
+**Run an eval gate** — score a classifier against a labeled corpus and fail if it
+misses a floor (the exact pattern barb and sift use):
+
+```python
+from shipwright_kit.eval import Sample, evaluate, gate
+
+corpus = [Sample("phish-login", "phishing"),
+          Sample("example.com", "benign"),
+          Sample("secure-phish", "phishing")]
+
+result = evaluate(
+    lambda text: "phishing" if "phish" in text else "benign",
+    corpus,
+    positive_pred=lambda pred: pred == "phishing",
+    positive_expected=lambda label: label == "phishing",
+)
+print(result.precision, result.recall)        # 1.0 1.0
+gate(result, min_precision=1.0, min_recall=0.9)  # raises EvalGateError if below
+```
+
+**Use the shared severity tiers** — one generic scale tools map their own verdicts
+onto, with accessible (Unicode-or-ASCII) labels:
+
+```python
+from shipwright_kit.design import Severity, tier_label
+
+Severity.OK, Severity.INFO, Severity.NOTICE, Severity.WARN, Severity.CRITICAL  # IntEnum 0..4
+print(tier_label(Severity.CRITICAL))  # ✗ CRITICAL
+print(tier_label(Severity.OK))        # ✓ OK
+```
+
+`import shipwright_kit` pulls in no `rich` or `pyfiglet` — the heavy deps load lazily only
+when you actually render. Full API: **[docs/library.md](docs/library.md)**.
+
+## The framework
+
+The repo contains **no project code**. Projects stay their own Git repositories and
+their own packages; locally you clone each into the **gitignored** `projects/`
+directory, where a [uv](https://docs.astral.sh/uv/) workspace ties them together for
+development:
+
+```
+shipwright/
+├─ shipwright_kit/          # the importable library (design / eval / security)
+├─ tooling/ruff-base.toml   # single source of truth for lint rules
+├─ templates/               # Copier scaffolder (python-cli) + release config
+├─ skills/ · personas/      # the agent operating layer (scaffold, onboard, review …)
+├─ .github/workflows/       # reusable python-ci.yml + python-release.yml (SHA-pinned)
+└─ projects/                # GITIGNORED, local-only — your projects plug in here
+```
+
+Work is promoted through gates; failing a rung blocks promotion:
+
+```
+commit → lint + unit (auto) → build → dogfood + eval (auto) →
+QM gate (manual) → beta sign-off (manual) → release
+```
+
+The reusable CI/CD that wires these gates, the Copier scaffolder (`templates/`), and
+the agent skills (`skills/`) and personas (`personas/`) all ship now. This repo runs
+the exact gates it gives the projects built with it.
+
+## Framework quickstart
+
+Requires Python 3.11+, [uv](https://docs.astral.sh/uv/), and
+[just](https://github.com/casey/just).
+
+```bash
+uv sync --dev              # create the dev environment
+uv run pre-commit install  # install the local gate
+just lint                  # ruff check + format-check
+just test                  # pytest
+```
+
+The local `pre-commit` gate runs the same lint/format/secret checks as CI; add
+`just test` (and `uv build`) for the test and build rungs CI also enforces.
+
+## Docs
+
+- **[docs/library.md](docs/library.md)** — per-module API reference (design / eval / security)
+- **[docs/release-policy.md](docs/release-policy.md)** — SemVer + release policy
+- **[docs/ci-cd.md](docs/ci-cd.md)** — the reusable CI/CD workflows
+- **[CHANGELOG.md](CHANGELOG.md)**
+
+## Security
+
+Report vulnerabilities privately via GitHub's
+[private vulnerability reporting](https://github.com/duathron/shipwright/security/advisories/new)
+(repo **Security** tab → **Report a vulnerability**). See [SECURITY.md](SECURITY.md).
+
+## License
+
+[MIT](LICENSE) © 2026 Christian Huhn

shipwright_kit-0.6.0/README.md

@@ -0,0 +1,135 @@
+# Shipwright
+
+![CI](https://github.com/duathron/shipwright/actions/workflows/ci.yml/badge.svg)
+![CodeQL](https://github.com/duathron/shipwright/actions/workflows/codeql.yml/badge.svg)
+![Coverage](https://img.shields.io/badge/coverage-%E2%89%A590%25-brightgreen.svg)
+![Types](https://img.shields.io/badge/types-mypy-blue.svg)
+![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)
+![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)
+
+Shipwright is two things that share one repo:
+
+- an installable, **import-light Python library** of shared dev-tooling runtime —
+  `shipwright_kit.design` (severity tiers + accessible output), `shipwright_kit.eval`
+  (detection-quality eval harness), `shipwright_kit.security` (a security pack);
+- an **AI-agent-operated development framework** — reusable CI/CD, a Copier
+  scaffolder, quality gates, and bundled agent skills + personas — that **dogfoods**
+  the library and the gates it hands to the projects built with it.
+
+The library is consumed today by two real tools: **barb** and **sift** both import
+`shipwright_kit.eval` to run their detection-quality gates.
+
+## Install
+
+The library is **not on PyPI** — the bare name `shipwright` belongs to an unrelated
+project, so the published distribution is **`shipwright-kit`** and the import name is
+**`shipwright_kit`**. For now, install from git:
+
+```bash
+uv pip install "git+https://github.com/duathron/shipwright@main"
+# then: import shipwright_kit
+```
+
+> [!NOTE]
+> Pin a release tag instead of `@main` for reproducible builds once a tagged
+> release of the `shipwright-kit` distribution is cut. Do **not** `pip install
+> shipwright` from PyPI — that is a different, unrelated package.
+
+The security pack needs no extra — it ships with the base install and registers
+through the `shipwright_kit.packs` entry point.
+
+## Library quickstart
+
+**Run an eval gate** — score a classifier against a labeled corpus and fail if it
+misses a floor (the exact pattern barb and sift use):
+
+```python
+from shipwright_kit.eval import Sample, evaluate, gate
+
+corpus = [Sample("phish-login", "phishing"),
+          Sample("example.com", "benign"),
+          Sample("secure-phish", "phishing")]
+
+result = evaluate(
+    lambda text: "phishing" if "phish" in text else "benign",
+    corpus,
+    positive_pred=lambda pred: pred == "phishing",
+    positive_expected=lambda label: label == "phishing",
+)
+print(result.precision, result.recall)        # 1.0 1.0
+gate(result, min_precision=1.0, min_recall=0.9)  # raises EvalGateError if below
+```
+
+**Use the shared severity tiers** — one generic scale tools map their own verdicts
+onto, with accessible (Unicode-or-ASCII) labels:
+
+```python
+from shipwright_kit.design import Severity, tier_label
+
+Severity.OK, Severity.INFO, Severity.NOTICE, Severity.WARN, Severity.CRITICAL  # IntEnum 0..4
+print(tier_label(Severity.CRITICAL))  # ✗ CRITICAL
+print(tier_label(Severity.OK))        # ✓ OK
+```
+
+`import shipwright_kit` pulls in no `rich` or `pyfiglet` — the heavy deps load lazily only
+when you actually render. Full API: **[docs/library.md](docs/library.md)**.
+
+## The framework
+
+The repo contains **no project code**. Projects stay their own Git repositories and
+their own packages; locally you clone each into the **gitignored** `projects/`
+directory, where a [uv](https://docs.astral.sh/uv/) workspace ties them together for
+development:
+
+```
+shipwright/
+├─ shipwright_kit/          # the importable library (design / eval / security)
+├─ tooling/ruff-base.toml   # single source of truth for lint rules
+├─ templates/               # Copier scaffolder (python-cli) + release config
+├─ skills/ · personas/      # the agent operating layer (scaffold, onboard, review …)
+├─ .github/workflows/       # reusable python-ci.yml + python-release.yml (SHA-pinned)
+└─ projects/                # GITIGNORED, local-only — your projects plug in here
+```
+
+Work is promoted through gates; failing a rung blocks promotion:
+
+```
+commit → lint + unit (auto) → build → dogfood + eval (auto) →
+QM gate (manual) → beta sign-off (manual) → release
+```
+
+The reusable CI/CD that wires these gates, the Copier scaffolder (`templates/`), and
+the agent skills (`skills/`) and personas (`personas/`) all ship now. This repo runs
+the exact gates it gives the projects built with it.
+
+## Framework quickstart
+
+Requires Python 3.11+, [uv](https://docs.astral.sh/uv/), and
+[just](https://github.com/casey/just).
+
+```bash
+uv sync --dev              # create the dev environment
+uv run pre-commit install  # install the local gate
+just lint                  # ruff check + format-check
+just test                  # pytest
+```
+
+The local `pre-commit` gate runs the same lint/format/secret checks as CI; add
+`just test` (and `uv build`) for the test and build rungs CI also enforces.
+
+## Docs
+
+- **[docs/library.md](docs/library.md)** — per-module API reference (design / eval / security)
+- **[docs/release-policy.md](docs/release-policy.md)** — SemVer + release policy
+- **[docs/ci-cd.md](docs/ci-cd.md)** — the reusable CI/CD workflows
+- **[CHANGELOG.md](CHANGELOG.md)**
+
+## Security
+
+Report vulnerabilities privately via GitHub's
+[private vulnerability reporting](https://github.com/duathron/shipwright/security/advisories/new)
+(repo **Security** tab → **Report a vulnerability**). See [SECURITY.md](SECURITY.md).
+
+## License
+
+[MIT](LICENSE) © 2026 Christian Huhn

shipwright_kit-0.6.0/pyproject.toml

@@ -0,0 +1,81 @@
+[build-system]
+# setuptools>=77 is required for the SPDX string-form `license = "MIT"` (PEP 639).
+requires = ["setuptools>=77.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+# PyPI distribution name. The bare `shipwright` is taken on PyPI (unrelated 6si
+# tool), so the dist is `shipwright-kit`; the IMPORT name is `shipwright_kit`.
+name = "shipwright-kit"
+version = "0.6.0"
+description = "Shipwright — AI-agent dev framework + import-light design/eval/security library"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Christian Huhn" }]
+keywords = ["ci", "dev-tooling", "eval", "design-tokens", "severity", "quality-gates"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Quality Assurance",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+rich = ["rich>=13.7"]
+banner = ["pyfiglet>=1.0"]
+
+[project.urls]
+Homepage = "https://github.com/duathron/shipwright"
+Repository = "https://github.com/duathron/shipwright"
+Documentation = "https://github.com/duathron/shipwright/blob/main/docs/library.md"
+Changelog = "https://github.com/duathron/shipwright/blob/main/CHANGELOG.md"
+Issues = "https://github.com/duathron/shipwright/issues"
+
+[project.entry-points."shipwright_kit.packs"]
+security = "shipwright_kit.security.theme:SecurityTheme"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "mypy>=1.10",
+    "ruff>=0.8",
+    "pre-commit>=4.0",
+    "hypothesis>=6.0",
+    "rich>=13.7",
+    "copier>=9",
+    "packaging",
+    "typer>=0.9",
+]
+
+[tool.setuptools.packages.find]
+include = ["shipwright_kit*"]
+
+[tool.setuptools.package-data]
+shipwright_kit = ["py.typed"]
+
+[tool.uv.workspace]
+members = ["projects/*"]
+
+[tool.ruff]
+extend = "tooling/ruff-base.toml"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--cov=shipwright_kit --cov-report=term-missing --cov-fail-under=90"
+
+[tool.coverage.run]
+source = ["shipwright_kit"]
+branch = true
+
+[tool.mypy]
+python_version = "3.11"
+files = ["shipwright_kit"]
+ignore_missing_imports = true

shipwright_kit-0.6.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

shipwright_kit-0.6.0/shipwright_kit/__init__.py

@@ -0,0 +1,3 @@
+"""Shipwright — design-token + tooling library."""
+
+__version__ = "0.6.0"

shipwright_kit-0.6.0/shipwright_kit/cli.py

@@ -0,0 +1,36 @@
+"""Typer application factory for Shipwright CLI tools.
+
+Thin, opinionated defaults so every scaffolded CLI is consistent
+(``add_completion=False``, ``no_args_is_help=True``) plus an optional
+``version`` command. Imports Typer at module load, so this submodule is NOT
+imported by ``shipwright_kit/__init__`` — ``import shipwright_kit`` stays
+typer-free (import-light). Consumers that import ``shipwright_kit.cli`` already
+depend on Typer.
+"""
+
+from __future__ import annotations
+
+import typer
+
+__all__ = ["build_typer"]
+
+
+def build_typer(name: str, help: str, *, version: str | None = None) -> typer.Typer:
+    """Return a Typer app with Shipwright's standard defaults. If ``version`` is
+    given, register a ``version`` command that prints it."""
+    app = typer.Typer(
+        name=name,
+        help=help,
+        add_completion=False,
+        no_args_is_help=True,
+    )
+    if version is not None:
+
+        @app.command()
+        def version_() -> None:  # registered as "version"
+            """Print the version."""
+            typer.echo(version)
+
+        version_.__name__ = "version"
+
+    return app

shipwright_kit-0.6.0/shipwright_kit/config.py

@@ -0,0 +1,53 @@
+"""Import-light config mechanism shared by Shipwright CLI tools.
+
+Owns the *mechanism* only — a secure per-tool app directory, ordered-candidate
+config-file resolution, and a resolve->load->validate skeleton. The consumer
+injects its own yaml ``loader`` and (pydantic) ``validator`` callables, so this
+module stays stdlib-only and ``import shipwright_kit.config`` pulls no
+pyyaml/pydantic/typer. Each tool keeps its own config *schema*, env-override
+step, ``save_config`` and ``.env`` handling.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from pathlib import Path
+from typing import TypeVar
+
+__all__ = ["app_dir", "load_config", "resolve_config_file"]
+
+T = TypeVar("T")
+
+_OWNER_ONLY = 0o700
+
+
+def app_dir(name: str, *, create: bool = False, mode: int = _OWNER_ONLY) -> Path:
+    """Return ``~/.{name}``. With ``create=True`` make it owner-only (mkdir + chmod,
+    so a pre-existing loose-permission dir is hardened too)."""
+    d = Path.home() / f".{name}"
+    if create:
+        d.mkdir(mode=mode, parents=True, exist_ok=True)
+        d.chmod(mode)
+    return d
+
+
+def resolve_config_file(candidates: Iterable[Path | None]) -> Path | None:
+    """Return the first candidate that exists (``None`` entries skipped)."""
+    for c in candidates:
+        if c is not None and c.exists():
+            return c
+    return None
+
+
+def load_config(
+    candidates: Iterable[Path | None],
+    *,
+    loader: Callable[[Path], dict],
+    validator: Callable[[dict], T],
+) -> T:
+    """Resolve the first existing candidate, ``loader`` it to a dict, and
+    ``validator`` that dict into a config object. If no candidate exists, the
+    loader is NOT called and ``validator({})`` is returned."""
+    path = resolve_config_file(candidates)
+    data = loader(path) if path is not None else {}
+    return validator(data)

shipwright_kit-0.6.0/shipwright_kit/design/__init__.py

@@ -0,0 +1,24 @@
+"""Design tokens: tiers, glyphs, palette, console, output."""
+
+from .console import get_console, supports_color, supports_unicode
+from .glyphs import glyph, tier_label
+from .output import OUTPUT_SCHEMA_VERSION, VALID_FORMATS, Renderable, render
+from .palette import ColorblindTheme, DefaultTheme, Theme
+from .tiers import Severity, TierMappable
+
+__all__ = [
+    "Severity",
+    "TierMappable",
+    "glyph",
+    "tier_label",
+    "Theme",
+    "DefaultTheme",
+    "ColorblindTheme",
+    "get_console",
+    "supports_color",
+    "supports_unicode",
+    "VALID_FORMATS",
+    "Renderable",
+    "render",
+    "OUTPUT_SCHEMA_VERSION",
+]

shipwright_kit-0.6.0/shipwright_kit/design/banner.py

@@ -0,0 +1,21 @@
+"""Plain ASCII banner generator (dep-free). Optional figlet via the `banner`
+extra is imported lazily, with a plain fallback if it is absent."""
+
+from __future__ import annotations
+
+
+def _figlet(name: str) -> str:
+    try:
+        from pyfiglet import figlet_format
+    except (ModuleNotFoundError, ImportError, TypeError):
+        return name.upper()
+    return figlet_format(name).rstrip("\n")
+
+
+def make_banner(name: str, version: str, tagline: str = "", *, figlet: bool = False, ascii_only: bool = False) -> str:
+    """Return a banner string. Caller decides where to print it (typically stderr)."""
+    title = _figlet(name) if figlet else name.upper()
+    info = f"v{version}" + (f" | {tagline}" if tagline else "")
+    width = max([len(line) for line in title.splitlines()] + [len(info), 12])
+    rule = ("-" if ascii_only else "─") * width
+    return "\n".join([title, rule, info])

shipwright_kit-0.6.0/shipwright_kit/design/console.py

@@ -0,0 +1,33 @@
+"""Accessibility-aware console helpers. Rich is imported lazily inside
+`get_console` so `import shipwright_kit` stays light."""
+
+from __future__ import annotations
+
+import os
+import sys
+
+
+def supports_color(stream=None) -> bool:
+    stream = stream if stream is not None else sys.stdout
+    if os.environ.get("NO_COLOR"):
+        return False
+    isatty = getattr(stream, "isatty", None)
+    return bool(isatty and isatty())
+
+
+def supports_unicode(stream=None) -> bool:
+    stream = stream if stream is not None else sys.stdout
+    enc = (getattr(stream, "encoding", "") or "").lower()
+    if "utf" in enc:
+        return True
+    return bool(os.environ.get("WT_SESSION") or os.environ.get("ANSICON"))
+
+
+def get_console(*, no_color: bool = False, force_terminal: bool | None = None):
+    """Return a configured Rich Console (lazy import). Requires the `rich` extra."""
+    try:
+        from rich.console import Console
+    except ModuleNotFoundError as exc:  # pragma: no cover
+        raise RuntimeError("rich output requires `pip install shipwright-kit[rich]`") from exc
+    use_color = supports_color() and not no_color
+    return Console(no_color=not use_color, force_terminal=force_terminal, safe_box=not supports_unicode())

shipwright_kit-0.6.0/shipwright_kit/design/glyphs.py

@@ -0,0 +1,30 @@
+"""Per-tier glyphs with an ASCII fallback. Rule: a tier indicator always
+renders symbol + label, never color alone (the #1 colorblind fix)."""
+
+from __future__ import annotations
+
+from .tiers import Severity
+
+_UNICODE: dict[Severity, str] = {
+    Severity.OK: "✓",
+    Severity.INFO: "ℹ",
+    Severity.NOTICE: "•",
+    Severity.WARN: "⚠",
+    Severity.CRITICAL: "✗",
+}
+_ASCII: dict[Severity, str] = {
+    Severity.OK: "OK",
+    Severity.INFO: "i",
+    Severity.NOTICE: "*",
+    Severity.WARN: "!",
+    Severity.CRITICAL: "XX",
+}
+
+
+def glyph(tier: Severity, *, ascii_only: bool = False) -> str:
+    return (_ASCII if ascii_only else _UNICODE)[tier]
+
+
+def tier_label(tier: Severity, *, ascii_only: bool = False) -> str:
+    """Symbol + label — never color/symbol alone."""
+    return f"{glyph(tier, ascii_only=ascii_only)} {tier.label}"

shipwright_kit-0.6.0/shipwright_kit/design/output.py

@@ -0,0 +1,60 @@
+"""Output-format contract. Core formats are stdlib-only; `rich` is lazy.
+`console` is a distinct reduced-density plain formatter (not Rich-no-color)."""
+
+from __future__ import annotations
+
+import csv as _csv
+import io
+import json
+from typing import Protocol, runtime_checkable
+
+from .glyphs import tier_label
+from .tiers import Severity
+
+VALID_FORMATS = ("rich", "console", "json", "ndjson", "csv")
+
+# render(fmt="json") envelope contract version (G10). Bump = structural break;
+# update the golden test + a migration note (docs/release-policy.md).
+OUTPUT_SCHEMA_VERSION = 1
+
+
+@runtime_checkable
+class Renderable(Protocol):
+    def rows(self) -> list[dict]: ...
+
+    def tier(self) -> Severity: ...
+
+
+def render(obj: Renderable, fmt: str = "console", *, ascii_only: bool = False) -> str:
+    if fmt not in VALID_FORMATS:
+        raise ValueError(f"unknown format {fmt!r}; valid: {', '.join(VALID_FORMATS)}")
+    rows = list(obj.rows())
+    if fmt == "json":
+        return json.dumps({"schema_version": OUTPUT_SCHEMA_VERSION, "tier": obj.tier().label, "rows": rows}, indent=2)
+    if fmt == "ndjson":
+        return "\n".join(json.dumps(r) for r in rows)
+    if fmt == "csv":
+        if not rows:
+            return ""
+        buf = io.StringIO()
+        writer = _csv.DictWriter(buf, fieldnames=list(rows[0].keys()))
+        writer.writeheader()
+        writer.writerows(rows)
+        return buf.getvalue()
+    if fmt == "console":
+        head = tier_label(obj.tier(), ascii_only=ascii_only)
+        body = ["  " + " ".join(f"{k}={v}" for k, v in r.items()) for r in rows]
+        return "\n".join([head, *body])
+    # fmt == "rich" — lazy import
+    from rich.console import Console
+    from rich.table import Table
+
+    table = Table()
+    if rows:
+        for key in rows[0]:
+            table.add_column(str(key))
+        for r in rows:
+            table.add_row(*[str(v) for v in r.values()])
+    buf = io.StringIO()
+    Console(file=buf, force_terminal=False, no_color=True).print(table)
+    return buf.getvalue()