grison 0.1.0__py3-none-any.whl

grison/__init__.py

@@ -0,0 +1,9 @@
+"""grison — a markdown hub between security scanners and Valiente's infra.
+
+Everything is a *source*, *transform*, or *sink* of markdown. See the module
+layout (ports & adapters): ``model`` (schema), ``scanners`` (source adapters),
+``markdown`` (serialization + HTML⇄md converter), ``sinks`` (file sink),
+``remote`` (Ghostwriter + BookStack), and ``cli``.
+"""
+
+__version__ = "0.1.0"

grison/cli.py

@@ -0,0 +1,304 @@
+"""grison CLI — three verbs: ``parse``, ``status``, ``sync``.
+
+The path names the backend (``findings/`` ⇄ Ghostwriter, ``methodology/`` ⇄
+BookStack); location decides identity; the first ``sync`` bootstraps the workspace.
+``parse`` and ``status`` are offline; ``sync`` reconciles findings with Ghostwriter
+and methodology with BookStack (push/pull/collision derived per record).
+"""
+
+from __future__ import annotations
+
+import fcntl
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from grison.model import FindingType
+from grison.remote.bookstack import BookStackClient
+from grison.remote.bootstrap import bootstrap_workspace
+from grison.remote.creds import MissingCreds
+from grison.remote.creds import load as load_creds
+from grison.remote.ghostwriter import GhostwriterClient
+from grison.remote.methodology import MethResult, sync_methodology
+from grison.remote.sync import SyncResult
+from grison.remote.sync import sync as run_sync
+from grison.sinks import ParseSummary, run_parse
+from grison.validate import validate_file
+from grison.workspace import bootstrap_tree, inbox_dir
+
+app = typer.Typer(
+    name="grison",
+    help="A markdown hub between security scanners and Valiente's Ghostwriter + BookStack.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+@app.callback()
+def _root() -> None:
+    """grison — parse scanner artifacts to markdown, then status/sync with the remotes."""
+
+
+@app.command()
+def parse(
+    paths: Annotated[list[Path], typer.Argument(help="Scanner export file(s) or dir(s).")],
+    scanner: Annotated[
+        str | None,
+        typer.Option("--scanner", help="Force a scanner type instead of auto-detecting."),
+    ] = None,
+    out: Annotated[
+        Path | None,
+        typer.Option("-o", "--out", help="Output dir (default: findings/inbox/)."),
+    ] = None,
+    finding_type: Annotated[
+        FindingType | None,
+        typer.Option("--finding-type", help="Override the per-scanner finding-type default."),
+    ] = None,
+    min_severity: Annotated[
+        str | None,
+        typer.Option("--min-severity", help="Keep only e.g. 'high,critical' or 'medium-critical'."),
+    ] = None,
+    dry_run: Annotated[bool, typer.Option("--dry-run", help="Preview without writing.")] = False,
+) -> None:
+    """Turn scanner export(s) into markdown findings in findings/inbox/ (offline)."""
+    if out is None:
+        bootstrap_tree(Path.cwd())  # the binary scaffolds; no init
+        out_dir = inbox_dir(Path.cwd())
+    else:
+        out_dir = out
+    summary = run_parse(
+        paths,
+        out_dir,
+        scanner=scanner,
+        finding_type=finding_type,
+        min_severity=min_severity,
+        dry_run=dry_run,
+    )
+    _print_parse_summary(summary, out_dir, dry_run=dry_run)
+    if summary.errors:
+        raise typer.Exit(code=1)
+
+
+@app.command()
+def status(
+    paths: Annotated[list[Path], typer.Argument(help="Finding markdown file(s) or dir(s).")],
+) -> None:
+    """Report per-record validity (schema / enum / CVSS / CWE / GW whitelist)."""
+    files = _resolve_md(paths)
+    if not files:
+        typer.secho("no markdown files found", fg=typer.colors.YELLOW)
+        raise typer.Exit(code=0)
+
+    invalid = 0
+    for f in files:
+        errors = validate_file(f)
+        if errors:
+            invalid += 1
+            typer.secho(f"INVALID  {f}", fg=typer.colors.RED)
+            for e in errors:
+                typer.echo(f"           - {e}")
+        else:
+            typer.secho(f"valid    {f}", fg=typer.colors.GREEN)
+
+    valid = len(files) - invalid
+    typer.echo("")
+    fg = typer.colors.RED if invalid else typer.colors.GREEN
+    typer.secho(f"{valid} valid, {invalid} invalid", fg=fg)
+    if invalid:
+        raise typer.Exit(code=1)
+
+
+@app.command()
+def sync(
+    dry_run: Annotated[
+        bool, typer.Option("--dry-run", help="Preview the plan, write nothing (== status).")
+    ] = False,
+    force_local: Annotated[
+        Path | None,
+        typer.Option("--force-local", help="Resolve a file's collision by taking local (push)."),
+    ] = None,
+    force_remote: Annotated[
+        Path | None,
+        typer.Option("--force-remote", help="Resolve a file's collision by taking remote (pull)."),
+    ] = None,
+) -> None:
+    """Reconcile the workspace with Ghostwriter — push/pull/collision derived per record.
+
+    Bootstraps on first run. Direction isn't chosen: a locally-edited record pushes, a
+    remote-changed one pulls, and a record changed on both sides is surfaced (never
+    overwritten). Every remote write is snapshot-backed.
+    """
+    root = Path.cwd()
+    boot = bootstrap_workspace(root)
+    creds = load_creds(root)
+    try:
+        creds.require_ghostwriter()
+    except MissingCreds as e:
+        if boot.env_created:
+            typer.secho(f"Scaffolded workspace + wrote {boot.env_path}", fg=typer.colors.GREEN)
+        typer.secho(str(e), fg=typer.colors.YELLOW)
+        raise typer.Exit(code=1) from None
+
+    fl = {force_local.resolve()} if force_local else set()
+    fr = {force_remote.resolve()} if force_remote else set()
+    with _workspace_lock(root):  # one sync at a time per workspace (GW has no compare-and-swap)
+        with GhostwriterClient(creds) as client:
+            result = run_sync(root, client, dry_run=dry_run, force_local=fl, force_remote=fr)
+        _print_sync_summary(result, dry_run=dry_run)
+        bad = bool(
+            result.collisions or result.invalid or result.mass_change_blocked or result.errors
+        )
+
+        if creds.bs_url and creds.bs_token_id and creds.bs_token_secret:
+            with BookStackClient(creds) as bs:
+                m = sync_methodology(root, bs, dry_run=dry_run, force_local=fl, force_remote=fr)
+            _print_meth_summary(m, dry_run=dry_run)
+            bad = bad or bool(
+                m.collisions or m.invalid or m.drift or m.artifacts
+                or m.mass_change_blocked or m.errors
+            )
+
+    if bad:
+        raise typer.Exit(code=1)
+
+
+@contextmanager
+def _workspace_lock(root: Path) -> Iterator[None]:
+    """Serialize sync runs per workspace via an exclusive flock on .grison/lock."""
+    lock_path = root / ".grison" / "lock"
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+    fh = lock_path.open("w", encoding="utf-8")
+    try:
+        try:
+            fcntl.flock(fh, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except BlockingIOError:
+            typer.secho(
+                "another grison sync is already running in this workspace (.grison/lock held)",
+                fg=typer.colors.RED,
+            )
+            raise typer.Exit(code=1) from None
+        yield
+    finally:
+        fcntl.flock(fh, fcntl.LOCK_UN)
+        fh.close()
+
+
+def _print_meth_summary(m: MethResult, *, dry_run: bool) -> None:
+    tense = "would " if dry_run else ""
+    typer.secho(
+        f"methodology: {tense}pull {len(m.pulled)}, {tense}push {len(m.pushed)}, "
+        f"{tense}create {len(m.created)}  ({len(m.unchanged)} clean, {len(m.repaired)} repaired)",
+        fg=typer.colors.GREEN,
+    )
+    if m.snapshot_dir:
+        typer.echo(f"snapshot: {m.snapshot_dir}")
+    if m.mass_change_blocked:
+        typer.secho(
+            "MASS-CHANGE GUARD tripped on methodology — writes withheld.", fg=typer.colors.RED
+        )
+    for p, why in m.drift:
+        typer.secho(f"structure-drift  {p}: {why}", fg=typer.colors.RED)
+    for p, what in m.artifacts:
+        typer.secho(f"artifact  {p}: {what}", fg=typer.colors.RED)
+    if m.collisions:
+        typer.secho(
+            f"{len(m.collisions)} collision(s) — hand-merge then --force-*:", fg=typer.colors.RED
+        )
+        for p in m.collisions:
+            typer.echo(f"  ! {p}")
+    for p in m.invalid:
+        typer.secho(f"broken link  {p}", fg=typer.colors.RED)
+    for p, reason in m.skipped:
+        typer.secho(f"skipped  {p}: {reason}", fg=typer.colors.YELLOW)
+    for e in m.errors:
+        typer.secho(f"  error: {e}", fg=typer.colors.RED)
+
+
+def _print_sync_summary(result: SyncResult, *, dry_run: bool) -> None:
+    tense = "would " if dry_run else ""
+    ev = ""
+    if result.evidence_up or result.evidence_down or result.evidence_deleted:
+        ev = f"  [evidence ↑{result.evidence_up} ↓{result.evidence_down}"
+        if result.evidence_deleted:
+            ev += f" ✕{result.evidence_deleted}"
+        ev += "]"
+    typer.secho(
+        f"{tense}pull {len(result.pulled)}, {tense}push {len(result.pushed)}, "
+        f"{tense}insert {len(result.inserted)}  ({len(result.unchanged)} clean, "
+        f"{len(result.repaired)} repaired){ev}",
+        fg=typer.colors.GREEN,
+    )
+    if result.snapshot_dir:
+        typer.echo(f"snapshot: {result.snapshot_dir}")
+    if result.mass_change_blocked:
+        typer.secho(
+            "MASS-CHANGE GUARD tripped — remote writes withheld. Re-run a narrower path "
+            "or confirm with a targeted sync.",
+            fg=typer.colors.RED,
+        )
+    if result.collisions:
+        typer.secho(
+            f"{len(result.collisions)} collision(s) — hand-merge then --force-local/-remote:",
+            fg=typer.colors.RED,
+        )
+        for p in result.collisions:
+            typer.echo(f"  ! {p}  (remote at {p.with_suffix('.remote.md').name})")
+    if result.invalid:
+        typer.secho(f"{len(result.invalid)} broken link(s) (id set, no sync base) — re-link with "
+                    "--force-remote/--force-local:", fg=typer.colors.RED)
+        for p in result.invalid:
+            typer.echo(f"  ? {p}")
+    for p, reason in result.skipped:
+        typer.secho(f"skipped  {p}: {reason}", fg=typer.colors.YELLOW)
+    for e in result.errors:
+        typer.secho(f"  error: {e}", fg=typer.colors.RED)
+
+
+def _resolve_md(paths: list[Path]) -> list[Path]:
+    files: list[Path] = []
+    for p in paths:
+        if p.is_dir():
+            files.extend(sorted(p.glob("*.md")))
+        elif p.is_file():
+            files.append(p)
+    return files
+
+
+def _print_parse_summary(summary: ParseSummary, out_dir: Path, *, dry_run: bool) -> None:
+    n_files = sum(summary.files_parsed.values())
+    by_scanner = ", ".join(f"{k}: {v}" for k, v in sorted(summary.files_parsed.items()))
+    typer.secho(
+        f"Parsed {len(summary.findings)} finding(s) from {n_files} file(s)"
+        + (f" ({by_scanner})" if by_scanner else ""),
+        fg=typer.colors.GREEN,
+    )
+
+    sink = summary.sink
+    if sink is not None:
+        verb = "Would write" if dry_run else "Wrote"
+        typer.echo(f"{verb} {len(sink.written)} → {out_dir}  ({len(sink.unchanged)} unchanged)")
+
+    for path, reason in summary.skipped_files:
+        typer.secho(f"skipped  {path.name}: {reason}", fg=typer.colors.YELLOW)
+
+    if summary.warnings:
+        typer.secho(f"{len(summary.warnings)} warning(s):", fg=typer.colors.YELLOW)
+        for w in summary.warnings:
+            typer.echo(f"  - {w}")
+
+    if summary.errors:
+        typer.secho(f"{len(summary.errors)} finding(s) failed validation:", fg=typer.colors.RED)
+        for e in summary.errors:
+            typer.echo(f"  - {e}")
+
+
+def main() -> None:
+    """Console-script entry point (``grison``)."""
+    app()
+
+
+if __name__ == "__main__":
+    main()

grison/markdown/__init__.py

@@ -0,0 +1,33 @@
+"""Markdown layer: the HTML⇄markdown converter, Finding⇄document serialization,
+and scanner-IR → house-schema mapping.
+
+The GW field vocabulary is tiny and closed; the converter fails loudly on anything
+outside it. A Finding's prose fields are markdown; ``##`` section headers are grison
+structure that map to Ghostwriter's separate fields.
+"""
+
+from __future__ import annotations
+
+from grison.markdown.converter import ConverterError, html_to_md, md_to_html
+from grison.markdown.document import (
+    DocumentError,
+    finding_to_markdown,
+    markdown_to_finding,
+)
+from grison.markdown.mapping import (
+    MappingResult,
+    default_finding_type,
+    ir_to_finding,
+)
+
+__all__ = [
+    "ConverterError",
+    "DocumentError",
+    "MappingResult",
+    "default_finding_type",
+    "finding_to_markdown",
+    "html_to_md",
+    "ir_to_finding",
+    "markdown_to_finding",
+    "md_to_html",
+]

grison/markdown/converter.py

@@ -0,0 +1,303 @@
+"""Bespoke HTML<->markdown converter for the tiny closed vocabulary Ghostwriter's
+rich-text fields accept.
+
+Ghostwriter finding fields render a small, fixed subset of HTML (paragraphs,
+unordered lists, bold/code/em/links/hard-breaks, plus TinyMCE's cosmetic
+``<span>`` highlight wrapper). grison round-trips those fields against local
+markdown, so this module hand-rolls both directions instead of depending on a
+general-purpose HTML/markdown library: anything outside the whitelist below
+must fail loudly (:class:`ConverterError`) rather than degrade silently or
+get dropped on the floor.
+
+Whitelist (both directions):
+  block:  ``<p>`` <-> paragraph, ``<ul><li>`` <-> ``- `` list item
+  inline: ``<strong>`` <-> ``**bold**``, ``<code>`` <-> `` `code` ``,
+          ``<em>`` <-> ``*em*``/``_em_``, ``<a href>`` <-> ``[text](url)``,
+          ``<br>`` <-> a hard line break inside a paragraph
+  ``<span>`` is unwrapped (kept, tag dropped) rather than rejected, since
+  TinyMCE wraps highlighted text in it.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from html.parser import HTMLParser
+
+
+class ConverterError(ValueError):
+    """Raised when HTML or markdown outside the tiny closed GW vocabulary is seen."""
+
+
+_BLOCK_TAGS = {"p", "ul", "li"}
+_INLINE_TAGS = {"strong", "code", "em", "a", "br"}
+_UNWRAP_TAGS = {"span"}
+_ALLOWED_TAGS = _BLOCK_TAGS | _INLINE_TAGS | _UNWRAP_TAGS
+
+
+def _esc(text: str) -> str:
+    """HTML-escape text/attribute content. ``"`` is escaped too so a URL containing a
+    quote can't break out of the ``href="…"`` attribute and inject markup."""
+    return (
+        text.replace("&", "&amp;")
+        .replace("<", "&lt;")
+        .replace(">", "&gt;")
+        .replace('"', "&quot;")
+    )
+
+
+# --- html -> markdown -------------------------------------------------------
+
+
+@dataclass
+class _Node:
+    tag: str
+    attrs: dict[str, str] = field(default_factory=dict)
+    children: list[_Node | str] = field(default_factory=list)
+
+
+class _TreeBuilder(HTMLParser):
+    """Builds a tiny tree from an HTML fragment, rejecting non-whitelisted tags."""
+
+    def __init__(self) -> None:
+        super().__init__(convert_charrefs=True)
+        self.root = _Node("root")
+        self.stack: list[_Node] = [self.root]
+
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        self._open(tag, attrs)
+
+    def handle_startendtag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        self._open(tag, attrs)  # self-closing form, e.g. <br/>
+
+    def _open(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        if tag not in _ALLOWED_TAGS:
+            raise ConverterError(f"unsupported HTML tag: <{tag}>")
+        if tag == "br":
+            self.stack[-1].children.append(_Node("br"))
+            return
+        node_attrs: dict[str, str] = {}
+        if tag == "a":
+            for name, value in attrs:
+                if name == "href":
+                    node_attrs["href"] = value or ""
+        node = _Node(tag, node_attrs)
+        self.stack[-1].children.append(node)
+        self.stack.append(node)
+
+    def handle_endtag(self, tag: str) -> None:
+        if tag == "br":
+            return
+        if tag not in _ALLOWED_TAGS:
+            raise ConverterError(f"unsupported HTML tag: </{tag}>")
+        if len(self.stack) <= 1 or self.stack[-1].tag != tag:
+            raise ConverterError(f"mismatched closing tag: </{tag}>")
+        self.stack.pop()
+
+    def handle_data(self, data: str) -> None:
+        self.stack[-1].children.append(data)
+
+
+def html_to_md(html: str) -> str:
+    """Convert a GW rich-text HTML fragment to markdown."""
+    builder = _TreeBuilder()
+    builder.feed(html)
+    builder.close()
+    if len(builder.stack) != 1:
+        raise ConverterError(f"unclosed HTML tag: <{builder.stack[-1].tag}>")
+    blocks = _group_top_level(builder.root.children)
+    return "\n\n".join(_render_block(block) for block in blocks)
+
+
+def _group_top_level(children: list[_Node | str]) -> list[_Node]:
+    """Split top-level children into p/ul blocks, wrapping stray inline content
+    in an implicit paragraph and dropping insignificant top-level whitespace."""
+    blocks: list[_Node] = []
+    buffer: list[_Node | str] = []
+
+    def flush() -> None:
+        if buffer:
+            blocks.append(_Node("p", children=list(buffer)))
+            buffer.clear()
+
+    for child in children:
+        if isinstance(child, str) and child.strip() == "":
+            continue
+        if isinstance(child, _Node) and child.tag in ("p", "ul"):
+            flush()
+            blocks.append(child)
+        else:
+            buffer.append(child)
+    flush()
+    return blocks
+
+
+def _render_block(node: _Node) -> str:
+    if node.tag == "p":
+        return _render_inline(node.children)
+    if node.tag == "ul":
+        lines = []
+        for li in node.children:
+            if isinstance(li, str):
+                if li.strip() == "":
+                    continue
+                raise ConverterError("stray text directly inside <ul> (expected <li>)")
+            if li.tag != "li":
+                raise ConverterError(f"unsupported <ul> child: <{li.tag}>")
+            lines.append("- " + _render_li(li))
+        return "\n".join(lines)
+    raise ConverterError(f"unsupported block-level tag: <{node.tag}>")
+
+
+def _render_li(li: _Node) -> str:
+    """Render a list item, unwrapping the ``<p>`` GW wraps item content in and
+    flattening any nested ``<ul>`` into sibling items.
+
+    The corpus impact/mitigation/references fields are ``<ul><li><p>…</p></li></ul>``;
+    a bare ``<li>`` of inline content is rendered directly (preserving inline spacing).
+    Nested lists (``<li>…<ul>…</ul></li>``) are flattened — markdown here is
+    intentionally single-level, and flattening round-trips stably.
+    """
+    if not any(isinstance(c, _Node) and c.tag in ("p", "ul") for c in li.children):
+        return _render_inline(li.children)
+    inline_parts: list[str] = []
+    nested: list[str] = []
+    for child in li.children:
+        if isinstance(child, _Node) and child.tag == "ul":
+            nested.extend(_render_block(child).split("\n"))  # already "- …" lines
+        elif isinstance(child, _Node) and child.tag == "p":
+            rendered = _render_inline(child.children)
+            if rendered:
+                inline_parts.append(rendered)
+        elif isinstance(child, str):
+            if child.strip():
+                inline_parts.append(child.strip())
+        else:
+            rendered = _render_inline([child])
+            if rendered:
+                inline_parts.append(rendered)
+    head = " ".join(inline_parts)
+    lines = ([head] if head else []) + nested
+    return "\n".join(lines)
+
+
+def _render_inline(nodes: list[_Node | str]) -> str:
+    parts = []
+    for n in nodes:
+        if isinstance(n, str):
+            parts.append(n)
+        elif n.tag == "br":
+            parts.append("\n")
+        elif n.tag == "strong":
+            parts.append(f"**{_render_inline(n.children)}**")
+        elif n.tag == "em":
+            parts.append(f"*{_render_inline(n.children)}*")
+        elif n.tag == "code":
+            parts.append(f"`{_render_code_text(n.children)}`")
+        elif n.tag == "a":
+            href = n.attrs.get("href", "")
+            parts.append(f"[{_render_inline(n.children)}]({href})")
+        elif n.tag == "span":
+            parts.append(_render_inline(n.children))
+        else:
+            raise ConverterError(f"unsupported tag in inline content: <{n.tag}>")
+    return "".join(parts)
+
+
+def _render_code_text(nodes: list[_Node | str]) -> str:
+    """<code> content is never inline-parsed, so just flatten its text (unwrapping
+    any cosmetic <span>, but rejecting any other nested tag)."""
+    parts = []
+    for n in nodes:
+        if isinstance(n, str):
+            parts.append(n)
+        elif n.tag == "span":
+            parts.append(_render_code_text(n.children))
+        else:
+            raise ConverterError(f"unsupported nested tag inside <code>: <{n.tag}>")
+    return "".join(parts)
+
+
+# --- markdown -> html --------------------------------------------------------
+
+_HEADING_RE = re.compile(r"^#{1,6}\s")
+_ORDERED_RE = re.compile(r"^\d+\.\s")
+_IMAGE_RE = re.compile(r"!\[[^\]]*\]\([^)]*\)")
+_BLOCKQUOTE_RE = re.compile(r"^>\s?")
+_TABLE_SEP_RE = re.compile(r"\|?\s*:?-+:?\s*(\|\s*:?-+:?\s*)+\|?")
+_SETEXT_EQ_RE = re.compile(r"=+")
+_RULE_RE = re.compile(r"-{2,}")
+
+_TOKEN_RE = re.compile(
+    r"`(?P<code>[^`]*)`"
+    r"|\*\*(?P<strong>.+?)\*\*"
+    r"|\[(?P<link_text>[^\]]*)\]\((?P<link_url>[^)]*)\)"
+    r"|\*(?P<em1>.+?)\*"
+    r"|_(?P<em2>.+?)_"
+)
+
+
+def md_to_html(md: str) -> str:
+    """Convert markdown (the tiny closed GW subset) to an HTML fragment."""
+    blocks = re.split(r"\n\s*\n", md)
+    return "\n\n".join(_render_md_block(block) for block in blocks)
+
+
+def _render_md_block(block: str) -> str:
+    lines = block.split("\n")
+    for line in lines:
+        _check_line_whitelist(line)
+    if lines and all(_is_list_line(line) for line in lines):
+        items = "".join(f"<li>{_inline_to_html(line[2:])}</li>" for line in lines)
+        return f"<ul>{items}</ul>"
+    rendered = [_inline_to_html(line) for line in lines]
+    return f"<p>{'<br>'.join(rendered)}</p>"
+
+
+def _is_list_line(line: str) -> bool:
+    return line.startswith("- ") or line.startswith("* ")
+
+
+def _check_line_whitelist(line: str) -> None:
+    stripped = line.strip()
+    if _HEADING_RE.match(line):
+        raise ConverterError(f"unsupported markdown: ATX heading ({line!r})")
+    if _ORDERED_RE.match(line):
+        raise ConverterError(f"unsupported markdown: ordered list ({line!r})")
+    if _IMAGE_RE.search(line):
+        raise ConverterError(f"unsupported markdown: image ({line!r})")
+    if stripped.startswith("```"):
+        raise ConverterError(f"unsupported markdown: fenced code block ({line!r})")
+    if _BLOCKQUOTE_RE.match(line):
+        raise ConverterError(f"unsupported markdown: blockquote ({line!r})")
+    # A markdown table is identified by its separator row (---|---); a bare pipe is
+    # not — shell commands inside `code` legitimately contain ` | ` (e.g. `a | nc`).
+    if _TABLE_SEP_RE.fullmatch(stripped):
+        raise ConverterError(f"unsupported markdown: table ({line!r})")
+    if _SETEXT_EQ_RE.fullmatch(stripped):
+        raise ConverterError(f"unsupported markdown: setext heading underline ({line!r})")
+    if _RULE_RE.fullmatch(stripped):
+        raise ConverterError(f"unsupported markdown: setext heading underline or rule ({line!r})")
+
+
+def _inline_to_html(text: str) -> str:
+    out = []
+    pos = 0
+    for m in _TOKEN_RE.finditer(text):
+        if m.start() > pos:
+            out.append(_esc(text[pos : m.start()]))
+        if m.group("code") is not None:
+            out.append(f"<code>{_esc(m.group('code'))}</code>")
+        elif m.group("strong") is not None:
+            out.append(f"<strong>{_esc(m.group('strong'))}</strong>")
+        elif m.group("link_text") is not None:
+            href = _esc(m.group("link_url"))
+            link_text = _esc(m.group("link_text"))
+            out.append(f'<a href="{href}" target="_blank" rel="noopener">{link_text}</a>')
+        elif m.group("em1") is not None:
+            out.append(f"<em>{_esc(m.group('em1'))}</em>")
+        else:
+            out.append(f"<em>{_esc(m.group('em2'))}</em>")
+        pos = m.end()
+    out.append(_esc(text[pos:]))
+    return "".join(out)