messagefoundry-toolkit 0.5.0__py3-none-any.whl

messagefoundry_toolkit/__init__.py

@@ -0,0 +1,21 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Foundation, LLC and contributors
+"""MessageFoundry toolkit: the authoring and development commands, kept out of the engine wheel.
+
+ADR 0201 (BACKLOG #1192, ASVS 15.2.3) moves every command ``messagefoundry.cli_surface.CLI_TIERS``
+marks ``toolkit`` out of the engine's ``messagefoundry`` command and into this package, whose own
+command is ``messagefoundry-toolkit``. A production install carries the engine alone, so it neither
+includes this code nor exposes these commands.
+
+The toolkit may import the engine. The engine must never import the toolkit, and
+``tests/test_dependency_boundaries.py`` holds that direction with a text search over
+``messagefoundry/``.
+
+The distribution is ``messagefoundry-toolkit``, built from ``packaging/messagefoundry-toolkit/`` in
+lockstep with the engine: same version, same tag. Dev and CI environments do not install it. The
+engine's editable install already puts the repository root on the import path, so
+``python -m messagefoundry_toolkit`` runs this checkout's copy. ADR 0201 section 1 says why an
+editable install of this distribution would be a frozen copy instead.
+"""
+
+from __future__ import annotations

messagefoundry_toolkit/__main__.py

@@ -0,0 +1,216 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Foundation, LLC and contributors
+"""Command-line entrypoint for the MessageFoundry toolkit (ADR 0201).
+
+    messagefoundry-toolkit adr-analyze --adr-dir docs/adr --json   # ADR criteria->test coverage
+
+In a checkout, run it as ``python -m messagefoundry_toolkit``. Each command here is a row that
+``messagefoundry.cli_surface.CLI_TIERS`` marks ``toolkit``. The engine's ``messagefoundry`` command
+does not register these rows, and refuses them with a line naming this command.
+
+The process shell around dispatch is the engine's own, ``messagefoundry.cli_common.run_cli``: stream
+hardening, the last-resort exception hooks, the redacting stderr log sink and the JSON error floor.
+This module never imports ``messagefoundry.__main__``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+import unicodedata
+from collections.abc import Callable
+from importlib import metadata
+
+from messagefoundry import __version__
+from messagefoundry.cli_common import (
+    Dispatch,
+    HelpFormatter,
+    _emit_error,
+    _print_json,
+    _safe_print,
+    argv_wants_json,
+    run_cli,
+)
+from messagefoundry.cli_surface import TOOLKIT_COMMAND
+from messagefoundry.console_streams import harden_console_streams
+
+#: The two distributions whose versions must match (ADR 0201 section 1). The toolkit's distribution
+#: and command share one name, held in ``cli_surface`` so the engine's refusal names the same one.
+TOOLKIT_DISTRIBUTION = TOOLKIT_COMMAND
+ENGINE_DISTRIBUTION = "messagefoundry"
+
+
+def main(argv: list[str] | None = None) -> int:
+    # FIRST STATEMENT, as in every console entry point (BACKLOG #1875):
+    # tests/test_cp1252_console_safety.py reads it here. run_cli() hardens again, which is a no-op.
+    harden_console_streams()
+    args = sys.argv[1:] if argv is None else argv
+    mismatch = version_mismatch(metadata.version)
+    if mismatch is not None:
+        # Exit 2, the usage-error code, and not 1: no command ran, so no command's result is being
+        # reported. _emit_error keeps the JSON-XOR-text rule, and its own return value is 1.
+        _emit_error(mismatch, as_json=argv_wants_json(args))
+        return 2
+    return run_cli(args, _build_parser)
+
+
+def version_mismatch(version_of: Callable[[str], str]) -> str | None:
+    """The refusal line when the installed toolkit and engine differ in version, or None (AC-4).
+
+    ``version_of`` is ``importlib.metadata.version``, passed in so a test can supply the metadata.
+    It compares METADATA WITH METADATA, never with the engine's live ``__version__``: the question
+    is which two distributions pip installed side by side. ``pip install -U messagefoundry``
+    upgrades the engine past the toolkit's ``==`` pin with only a resolver warning and exit 0, so
+    the pin alone does not hold the pair together.
+
+    With no toolkit metadata the check is skipped. That is every dev and CI environment, where the
+    toolkit is imported from the checkout beside the engine and the two cannot differ. With toolkit
+    metadata and no engine metadata, the pair cannot be checked, so the line refuses it.
+    """
+    try:
+        toolkit = version_of(TOOLKIT_DISTRIBUTION)
+    except metadata.PackageNotFoundError:
+        return None
+    try:
+        engine = version_of(ENGINE_DISTRIBUTION)
+    except metadata.PackageNotFoundError:
+        engine = "not installed"
+    if engine == toolkit:
+        return None
+    return (
+        f"{TOOLKIT_DISTRIBUTION} {toolkit} runs only beside {ENGINE_DISTRIBUTION} {toolkit}, but "
+        f"the installed {ENGINE_DISTRIBUTION} is {engine}. Install the two at one version."
+    )
+
+
+def _build_parser() -> tuple[argparse.ArgumentParser, Dispatch]:
+    """Build the toolkit's argument parser, and return it with the dispatch map.
+
+    Building has no side effect, as with the engine's builder, so a test can read the toolkit's
+    command surface without running ``main()``. The map returned is :data:`_DISPATCH` itself.
+    """
+    parser = argparse.ArgumentParser(
+        prog=TOOLKIT_COMMAND,
+        description=__doc__,
+        formatter_class=HelpFormatter,
+        allow_abbrev=False,  # the pre-parse refusal reads --help and --version by exact spelling
+    )
+    parser.add_argument("--version", action="version", version=f"{TOOLKIT_COMMAND} {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    adr_analyze = sub.add_parser(
+        "adr-analyze",
+        help="advisory spec-driven ADR coverage: acceptance-criteria->test links, missing criteria, "
+        "open clarifications (Secure Development Standards section 5)",
+    )
+    adr_analyze.add_argument(
+        "--adr-dir",
+        default="docs/adr",
+        help="ADR directory (default: docs/adr). Exits 2, with or without --strict, if it is "
+        "missing, is not a directory, or holds no ADR",
+    )
+    adr_analyze.add_argument(
+        "--repo-root",
+        default=None,
+        help="root for resolving test/fixture refs (default: adr-dir/../..; required when adr-dir "
+        "sits directly under a drive or filesystem root)",
+    )
+    adr_analyze.add_argument(
+        "--strict",
+        action="store_true",
+        help="exit 1 if any acceptance-criterion test ref is missing",
+    )
+    adr_analyze.add_argument("--json", action="store_true", help="emit JSON")
+
+    return parser, _DISPATCH
+
+
+def _adr_analyze(args: argparse.Namespace) -> int:
+    """Advisory spec-driven ADR coverage (Secure Development Standards §5). Reports acceptance-
+    criteria→test link coverage, Accepted ADRs missing criteria, and open ``- [ ]`` clarifications.
+
+    Two exit codes, and which one a condition gets is the point of the split. A *finding* is
+    advisory: a missing linked test/fixture, or one outside the repository root, exits 0, or 1
+    under ``--strict``. An *absent corpus*, or an ADR directory with no grandparent to default
+    the repository root to —
+    :attr:`~messagefoundry_toolkit.adr_analyze.AnalysisResult.error`, defined at
+    :func:`~messagefoundry_toolkit.adr_analyze.analyze_adrs` — exits **2 with or without
+    ``--strict``**, because the analyzer never ran. 2 and not 1 keeps "could not start" apart from
+    "ran and reported a problem", the same split the engine's ``_emit_store_open_error`` spends 2 on;
+    and not 0 because this subcommand is otherwise unfailable by default, so a withdrawn ADR set
+    would silently turn a failing report into a passing one.
+
+    That split is between this command's own codes. It does **not** separate 2 from argparse's own
+    usage-error 2, so a caller that must tell a withdrawn corpus from a mistyped flag has to read
+    the output, not the code. Every subcommand here inherits that, ``--json`` disambiguates it, and
+    widening it was not worth a third code."""
+    from messagefoundry_toolkit.adr_analyze import analyze_adrs
+
+    result = analyze_adrs(args.adr_dir, repo_root=args.repo_root)
+    if args.json:
+        _print_json(result.to_json(), compact=True)
+    if result.error is not None:
+        # JSON on stdout XOR the human line on stderr. Emitting both would reorder under `2>&1`: a
+        # piped stdout is block-buffered and stderr is not, so the error line would land ahead of
+        # the JSON and break the parse it was meant to protect. The JSON body is the full report
+        # with `error` inside it, and so is NOT _emit_store_open_error's bare {"error": ...}: `ok`
+        # has to stay readable for a consumer that branches on it and nothing else.
+        if not args.json:
+            print(f"error: {result.error}", file=sys.stderr)  # not _safe_print; see its docstring
+        return 2
+    if not args.json:
+        with_criteria = sum(1 for r in result.reports if r.has_criteria)
+        _print_record_line(
+            f"ADRs analyzed: {len(result.reports)} ({with_criteria} with acceptance criteria)"
+        )
+        for adr in result.accepted_without_criteria:
+            _print_record_line(f"  recommend: {adr} is Accepted with no acceptance-criteria block")
+        for adr, ref in result.coverage_gaps:
+            _print_record_line(f"  COVERAGE GAP: {adr} links a missing test/fixture: {ref}")
+        for adr, ref in result.outside_refs:
+            _print_record_line(
+                f"  OUTSIDE REPO: {adr} links a path outside the repository root, "
+                f"not checked: {ref}"
+            )
+        for adr, item in result.open_clarifications:
+            _print_record_line(f"  clarify: {adr} - open item: {item}")
+        _print_record_line(
+            "ok" if result.ok else "coverage gaps or links outside the repository found (advisory)"
+        )
+    return 1 if args.strict and not result.ok else 0
+
+
+#: Unicode categories escaped before record text reaches a terminal: C0 and C1 controls (an ANSI
+#: escape, a bell, a NUL), format characters (a bidirectional override that reorders the line) and
+#: the line and paragraph separators. An ADR is read as data, and a terminal acts on these.
+#: ``messagefoundry.controlchars.scrub_control_chars`` is not reused: its alphabet is C0 and DEL
+#: only, pinned that way for byte-oriented sinks, and so it passes C1 and the bidi overrides.
+_ESCAPED_CATEGORIES = frozenset({"Cc", "Cf", "Zl", "Zp"})
+
+
+def _print_record_line(line: str) -> None:
+    """``_safe_print`` a line that carries record text, with each character a terminal would act
+    on written as its Python escape (BACKLOG #2516). Every human line goes through here, so a new
+    one cannot forget the escape.
+
+    Local to the toolkit on purpose. ``_safe_print`` serves every engine command too, and its job
+    is the console codec, not what the line says. The JSON output needs nothing: ``json.dumps``
+    already escapes every control and non-ASCII character.
+
+    A backslash is doubled as well, so a record that spells ``\\x1b`` out in text cannot pass for
+    one that holds the escape character itself."""
+    _safe_print(
+        "".join(
+            ascii(ch)[1:-1] if ch == "\\" or unicodedata.category(ch) in _ESCAPED_CATEGORIES else ch
+            for ch in line
+        )
+    )
+
+
+_DISPATCH: dict[str, Callable[[argparse.Namespace], int]] = {
+    "adr-analyze": _adr_analyze,
+}
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

messagefoundry_toolkit/adr_analyze.py

@@ -0,0 +1,345 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Foundation, LLC and contributors
+"""``messagefoundry-toolkit adr-analyze`` — advisory spec-driven coverage report over the ADRs.
+
+The **analyze** half of the Secure Development Standards §5 spec-driven recommendations (R3): scan the
+Architecture Decision Records and report, **advisory-only** (never blocks a commit by default):
+
+* **Acceptance-criteria coverage** — for each ADR carrying an ``## Acceptance Criteria`` block (EARS,
+  per the ADR ``TEMPLATE.md`` / R1), the test/fixture each criterion links to (``→ tests/…``), and
+  whether that file exists on disk. A *coverage gap* is a criterion whose linked test is missing.
+  A link whose path climbs out of the repository root with ``..``, or names a DOS device such as
+  ``NUL`` or ``nul.py``, is reported as outside the repository on every platform, never probed.
+* **Missing criteria** — an ``Accepted`` ADR with no acceptance-criteria block (recommended to add).
+* **Open clarifications** — unchecked ``- [ ]`` task items (the "clarify" step): questions that
+  should be resolved before an ADR flips to ``Accepted``.
+
+Pure (filesystem reads only). Its **findings** are advisory: :attr:`AnalysisResult.ok` is
+informational and the CLI exits 0 unless ``--strict`` is passed, so it adds no new blocking gate —
+the §5 practices are recommended, not required. One condition is not a finding and is never
+advisory — an absent corpus; :func:`analyze_adrs` defines it and says why.
+"""
+
+from __future__ import annotations
+
+import os
+import posixpath
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+__all__ = [
+    "AcceptanceCriterion",
+    "AdrReport",
+    "AnalysisResult",
+    "analyze_adrs",
+]
+
+# How an ADR file is recognised. Quoted verbatim in the "nothing matched" error so the message and
+# the code state the same rule -- it is looser than the ``NNNN-`` naming convention it implements.
+_DISCOVERY_GLOB = "[0-9]*.md"
+
+# A reference inside an Acceptance-Criteria block pointing at a test or fixture, e.g.
+# ``tests/test_foo.py::test_bar`` or ``fixtures/IB_ACME/adt.hl7``. The ``::node`` pytest selector is
+# captured but dropped for the on-disk existence check.
+_REF_RE = re.compile(
+    r"(?:tests|fixtures|samples|harness)/[A-Za-z0-9_./\-]+(?:::[A-Za-z0-9_\-\[\]]+)?"
+)
+_STATUS_RE = re.compile(
+    r"status[^A-Za-z]*\b(Proposed|Accepted|Superseded|Rejected|Reserved|Dropped)\b", re.IGNORECASE
+)
+# Both run on an RSTRIPPED line, so the capture starts at a non-space and runs to the end. The old
+# forms, ``\s+(.*\S)\s*$`` on the raw line, retried every split of a whitespace-only tail and took
+# time quadratic in its length (BACKLOG #2516). ``rstrip`` and ``\s`` agree on what whitespace is.
+_UNCHECKED_RE = re.compile(r"^\s*[-*]\s+\[ \]\s+(\S.*)$")
+_HEADING_RE = re.compile(r"^#{1,6}\s+(\S.*)$")
+_BULLET_RE = re.compile(r"^\s*[-*]\s+\S")
+
+
+@dataclass(frozen=True)
+class AcceptanceCriterion:
+    """One acceptance-criterion bullet from an ADR's ``## Acceptance Criteria`` block."""
+
+    text: str
+    test_refs: list[str] = field(default_factory=list)
+    missing_refs: list[str] = field(default_factory=list)
+    #: Refs whose path climbs out of the repository root. Never probed, so never in ``missing_refs``.
+    outside_refs: list[str] = field(default_factory=list)
+
+    @property
+    def covered(self) -> bool:
+        """Covered iff it links ≥1 test/fixture, none missing on disk and none outside the root."""
+        return bool(self.test_refs) and not self.missing_refs and not self.outside_refs
+
+
+@dataclass(frozen=True)
+class AdrReport:
+    """The spec-driven analysis of a single ADR file."""
+
+    path: str
+    adr_id: str
+    title: str
+    status: str
+    criteria: list[AcceptanceCriterion] = field(default_factory=list)
+    open_clarifications: list[str] = field(default_factory=list)
+
+    @property
+    def accepted(self) -> bool:
+        return self.status.lower() == "accepted"
+
+    @property
+    def has_criteria(self) -> bool:
+        return bool(self.criteria)
+
+    @property
+    def coverage_gaps(self) -> list[str]:
+        return [ref for c in self.criteria for ref in c.missing_refs]
+
+    @property
+    def outside_refs(self) -> list[str]:
+        return [ref for c in self.criteria for ref in c.outside_refs]
+
+    def to_json(self) -> dict[str, object]:
+        return {
+            "path": self.path,
+            "adr_id": self.adr_id,
+            "title": self.title,
+            "status": self.status,
+            "criteria": [
+                {
+                    "text": c.text,
+                    "test_refs": c.test_refs,
+                    "missing_refs": c.missing_refs,
+                    "outside_refs": c.outside_refs,
+                }
+                for c in self.criteria
+            ],
+            "open_clarifications": self.open_clarifications,
+        }
+
+
+@dataclass(frozen=True)
+class AnalysisResult:
+    """The whole-ADR-set report.
+
+    ``error`` is a human-readable line naming the directory when there was no corpus to analyze,
+    or no repository root to check its links against, and ``None`` otherwise;
+    :func:`analyze_adrs` sets it and gives the reasoning.
+    """
+
+    reports: list[AdrReport]
+    error: str | None = None
+
+    @property
+    def coverage_gaps(self) -> list[tuple[str, str]]:
+        """``(adr_id, missing_ref)`` for every acceptance-criterion test link that does not exist."""
+        return [(r.adr_id, ref) for r in self.reports for ref in r.coverage_gaps]
+
+    @property
+    def outside_refs(self) -> list[tuple[str, str]]:
+        """``(adr_id, ref)`` for every test link whose path leaves the repository root."""
+        return [(r.adr_id, ref) for r in self.reports for ref in r.outside_refs]
+
+    @property
+    def accepted_without_criteria(self) -> list[str]:
+        return [r.adr_id for r in self.reports if r.accepted and not r.has_criteria]
+
+    @property
+    def open_clarifications(self) -> list[tuple[str, str]]:
+        return [(r.adr_id, item) for r in self.reports for item in r.open_clarifications]
+
+    @property
+    def ok(self) -> bool:
+        """True iff a corpus was analyzed and every acceptance-criterion link was found inside it."""
+        return self.error is None and not self.coverage_gaps and not self.outside_refs
+
+    def to_json(self) -> dict[str, object]:
+        return {
+            "ok": self.ok,
+            "error": self.error,
+            "adrs": [r.to_json() for r in self.reports],
+            "coverage_gaps": [{"adr": a, "ref": ref} for a, ref in self.coverage_gaps],
+            "outside_refs": [{"adr": a, "ref": ref} for a, ref in self.outside_refs],
+            "accepted_without_criteria": self.accepted_without_criteria,
+            "open_clarifications": [{"adr": a, "item": i} for a, i in self.open_clarifications],
+        }
+
+
+def _capture(pattern: re.Pattern[str], line: str) -> str | None:
+    """``pattern``'s capture over the rstripped ``line``, or None when it does not match.
+
+    The capture has no surrounding whitespace, so callers need not strip it."""
+    m = pattern.match(line.rstrip())
+    return m.group(1) if m else None
+
+
+def _sections(text: str) -> dict[str, list[str]]:
+    """Split markdown into ``{lowercased-heading: body-lines}`` (any heading level)."""
+    sections: dict[str, list[str]] = {}
+    current: str | None = None
+    for line in text.splitlines():
+        heading = _capture(_HEADING_RE, line)
+        if heading is not None:
+            current = heading.lower()
+            sections.setdefault(current, [])
+        elif current is not None:
+            sections[current].append(line)
+    return sections
+
+
+def _status(text: str) -> str:
+    m = _STATUS_RE.search(text)
+    return m.group(1).capitalize() if m else "Unknown"
+
+
+def _title(text: str, fallback: str) -> str:
+    for line in text.splitlines():
+        heading = _capture(_HEADING_RE, line)
+        if heading is not None:
+            return heading
+    return fallback
+
+
+#: The DOS device names. Windows opens the device for one of these wherever it sits in a path.
+#: ``_REF_RE`` admits ASCII only, so the superscript-digit ``COM`` and ``LPT`` forms and the ``$``
+#: names such as ``CONIN$`` cannot reach :func:`_inside`, and are not listed.
+_DOS_DEVICES = frozenset(
+    {"CON", "PRN", "AUX", "NUL"} | {f"{name}{n}" for name in ("COM", "LPT") for n in range(1, 10)}
+)
+
+
+def _inside(ref_path: str) -> str | None:
+    """A ref's path normalised, or None when it leaves the repository root.
+
+    Decided on the text alone, the same way on every host, so a ref that escapes is never probed.
+    ``_REF_RE`` admits only ``/`` as a separator and no drive, colon or leading slash, which leaves
+    two ways out. One is ``..``. The other is a component whose stem, the part before its first
+    dot with trailing dots and spaces dropped, is a DOS device name in any case: ``tests/NUL``,
+    ``tests/nul.py`` and ``fixtures/con.hl7`` are all outside. Windows itself disagrees by version
+    on a name with an extension -- windows-2022 opens the device for ``nul.py`` and newer releases
+    do not -- so the rule takes the older, wider reading rather than asking the host. A name that
+    only CONTAINS one stays inside: ``tests/null.py``, ``tests/console.py``, ``tests/com10.py``,
+    ``tests/my_nul.py``. The normalised form is what gets probed, so ``tests/sub/../x`` means the
+    same on every OS. A symbolic link inside the root is still followed; this reads the text, not
+    the tree.
+    """
+    norm = posixpath.normpath(ref_path)
+    if norm == ".." or norm.startswith("../"):
+        return None
+    for part in norm.split("/"):
+        if part.split(".", 1)[0].rstrip(". ").upper() in _DOS_DEVICES:
+            return None
+    return norm
+
+
+def _criteria(lines: list[str], repo_root: Path) -> list[AcceptanceCriterion]:
+    """Group the Acceptance-Criteria body into bullet items; an item is a criterion iff it contains
+    ``SHALL`` (the EARS keyword), filtering out the blockquote legend. Resolve each ``→`` test ref."""
+    items: list[list[str]] = []
+    for line in lines:
+        if line.lstrip().startswith(">"):
+            continue  # the EARS legend blockquote — not a criterion
+        if _BULLET_RE.match(line):
+            items.append([line])
+        elif items and line.strip():
+            items[-1].append(line)  # a continuation line of the current bullet (e.g. the → ref)
+    out: list[AcceptanceCriterion] = []
+    for item in items:
+        blob = "\n".join(item)
+        if "SHALL" not in blob.upper():
+            continue
+        text = item[0].strip().lstrip("-*").strip()
+        refs: list[str] = []
+        for m in _REF_RE.finditer(blob):
+            ref = m.group(0)
+            if ref not in refs:
+                refs.append(ref)
+        outside: list[str] = []
+        missing: list[str] = []
+        for ref in refs:
+            ref_path = _inside(ref.split("::", 1)[0])
+            if ref_path is None:
+                outside.append(ref)
+            elif not (repo_root / ref_path).exists():
+                missing.append(ref)
+        out.append(
+            AcceptanceCriterion(
+                text=text, test_refs=refs, missing_refs=missing, outside_refs=outside
+            )
+        )
+    return out
+
+
+def _clarifications(text: str) -> list[str]:
+    return [
+        item for line in text.splitlines() if (item := _capture(_UNCHECKED_RE, line)) is not None
+    ]
+
+
+def _parse_adr(path: Path, repo_root: Path) -> AdrReport:
+    text = path.read_text(encoding="utf-8")
+    return AdrReport(
+        path=str(path),
+        adr_id=path.stem.split("-", 1)[0],
+        title=_title(text, path.stem),
+        status=_status(text),
+        criteria=_criteria(_sections(text).get("acceptance criteria", []), repo_root),
+        open_clarifications=_clarifications(text),
+    )
+
+
+def analyze_adrs(adr_dir: str | Path, repo_root: str | Path | None = None) -> AnalysisResult:
+    """Analyze every ``NNNN-*.md`` ADR under ``adr_dir`` (README/TEMPLATE are skipped).
+
+    ``repo_root`` anchors the on-disk existence check for each ``→`` test/fixture reference; it
+    defaults to two levels above ``adr_dir`` (i.e. the repo root for the standard ``docs/adr`` layout).
+    Where ``adr_dir`` has no such grandparent, the default is refused through
+    :attr:`AnalysisResult.error`, which then names ``--repo-root`` instead of the corpus.
+
+    **AN ABSENT CORPUS IS AN ERROR, NOT AN EMPTY CLEAN RUN.** ``Path.glob`` yields nothing and
+    raises nothing for a directory that does not exist, so a missing ADR directory -- or one left
+    holding only its ``README.md`` and ``TEMPLATE.md`` scaffolding -- used to produce zero reports
+    and an :attr:`AnalysisResult.ok` of True. A check that cannot fail is worse than no check: it
+    would turn a withdrawn ADR set into a silent pass. So a path that does not exist, is not a
+    directory, or matches no ADR sets :attr:`AnalysisResult.error` -- a line naming the directory
+    -- and clears ``ok``; the CLI spends exit 2 on it whether or not ``--strict`` is passed.
+
+    **The error line says what was looked for, not why nothing was found.** ``Path.exists`` and
+    ``Path.glob`` both swallow ``OSError``, so a directory the process cannot read is
+    indistinguishable here from one that is absent or genuinely empty. A message naming a cause
+    the code cannot observe would send an operator to re-create a directory that is already there,
+    so each line below stays on the observation and admits the unreadable case.
+    """
+    adr_path = Path(adr_dir)
+    # Lexical ``abspath`` and not ``resolve()``: it makes the relative ``docs/adr`` default useful
+    # to an operator, and collapses any ``..`` they typed, without rewriting a path handed in
+    # through a symlink into its target.
+    shown = os.path.abspath(adr_path)
+    if not adr_path.exists():
+        return AnalysisResult(reports=[], error=f"no ADR directory found or readable at {shown}")
+    if not adr_path.is_dir():
+        return AnalysisResult(reports=[], error=f"the ADR path is not a directory: {shown}")
+    # ``is_file()`` because the glob matches a directory named like an ADR too, and handing one to
+    # ``_parse_adr`` raises where the whole point here is a reported error.
+    files = sorted(f for f in adr_path.glob(_DISCOVERY_GLOB) if f.is_file())
+    if not files:
+        return AnalysisResult(
+            reports=[], error=f"no file matching {_DISCOVERY_GLOB} found in {shown}"
+        )
+    if repo_root is not None:
+        root = Path(repo_root)
+    else:
+        # An ADR dir directly under a drive or filesystem root has no grandparent, and indexing
+        # ``parents[1]`` there raised IndexError (BACKLOG #2516). No default is right for it, so
+        # refuse and name the flag rather than guess at a root to probe.
+        resolved = adr_path.resolve()
+        if len(resolved.parents) < 2:
+            # Name the resolved path too: through a link, it is the one with no grandparent.
+            via = "" if str(resolved) == shown else f" (resolved: {resolved})"
+            return AnalysisResult(
+                reports=[],
+                error=f"no directory two levels above {shown}{via} to use as the repository "
+                "root; pass --repo-root",
+            )
+        root = resolved.parents[1]
+    return AnalysisResult(reports=[_parse_adr(f, root) for f in files])

messagefoundry_toolkit-0.5.0.dist-info/METADATA

@@ -0,0 +1,56 @@
+Metadata-Version: 2.5
+Name: messagefoundry-toolkit
+Version: 0.5.0
+Summary: Authoring and development tooling for MessageFoundry, kept out of the engine wheel (ADR 0201)
+Project-URL: Homepage, https://messagefoundry.org/
+Project-URL: Source, https://github.com/MEFORORG/MessageFoundry
+Project-URL: Contributing, https://github.com/MEFORORG/MessageFoundry/blob/main/CONTRIBUTING.md
+Author: MessageFoundry Foundation, LLC and contributors
+License-Expression: AGPL-3.0-or-later
+License-File: LICENSE
+License-File: NOTICE
+Keywords: authoring,development,healthcare,hl7,integration,tooling
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Healthcare Industry
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Communications
+Classifier: Topic :: Software Development
+Requires-Python: >=3.14
+Requires-Dist: messagefoundry==0.5.0
+Description-Content-Type: text/markdown
+
+# messagefoundry-toolkit
+
+The authoring and development commands for
+[**MessageFoundry**](https://github.com/MEFORORG/MessageFoundry), the open-source healthcare
+integration engine (HL7 v2.x and more), kept out of the engine wheel.
+
+A production host runs the engine alone. The engine's `messagefoundry` command carries only what a
+deployed engine needs to run, operate and check itself. The commands that help you write and test a
+configuration live here instead, behind their own command, `messagefoundry-toolkit`. The design and
+the reasons are in
+[ADR 0201](https://github.com/MEFORORG/MessageFoundry/blob/main/docs/adr/0201-a-messagefoundry-toolkit-distribution-carries-the-authoring-and-development-tooling-out-of-the-engine-wheel.md).
+
+> Released **in lockstep with the engine**: the toolkit and the engine carry the same version, and
+> the toolkit requires the engine at exactly that version. If the two installed versions ever differ,
+> the toolkit refuses to run and names both.
+
+Install it on an authoring machine, beside the engine and at the engine's version. A deploy does not
+need it, and a production host is better without it.
+
+## Use
+
+```text
+messagefoundry-toolkit adr-analyze --adr-dir docs/adr --json   # ADR acceptance-criteria coverage
+messagefoundry-toolkit --help                                  # every toolkit command
+```
+
+From a source checkout, run `python -m messagefoundry_toolkit` instead.
+
+The toolkit's commands move out of the engine one at a time. A command that has moved is refused by
+the engine's `messagefoundry` command, with a line naming `messagefoundry-toolkit <command>`.

messagefoundry_toolkit-0.5.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+messagefoundry_toolkit/__init__.py,sha256=s66NDjEkwGOD6iFNxgFq4Sdp0cFGXzWFWDVPWamJVpM,1229
+messagefoundry_toolkit/__main__.py,sha256=IJJsqZhsRay2k8--J-ctPsXRnj3cQ_nuCVvej8iyx2U,10301
+messagefoundry_toolkit/adr_analyze.py,sha256=AzquK2-QYHqC-e3ERPqyCevb2K86kSVivxyjb1x3Bv4,15403
+messagefoundry_toolkit-0.5.0.dist-info/METADATA,sha256=eMLCHZpVvknG9inYaN5ltMucD-JVEdGpUVvG46eGfzk,2756
+messagefoundry_toolkit-0.5.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+messagefoundry_toolkit-0.5.0.dist-info/entry_points.txt,sha256=-ckmYTCqssV_KKRnqCwjiP5mbxuOIZ2ItHXvyfmvpjc,80
+messagefoundry_toolkit-0.5.0.dist-info/licenses/LICENSE,sha256=jVa0BUaKrRH4erV2P5AeJ24I2WRv9chIGxditreJ6e0,34524
+messagefoundry_toolkit-0.5.0.dist-info/licenses/NOTICE,sha256=Emp1QFl9pG7lwz68sH0SLRLfWlQjAILmiTWeokcZW9I,1823
+messagefoundry_toolkit-0.5.0.dist-info/RECORD,,

messagefoundry_toolkit-0.5.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

messagefoundry_toolkit-0.5.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+messagefoundry-toolkit = messagefoundry_toolkit.__main__:main