syncade 0.6.2__py3-none-any.whl

syncade/persistence/_findings_verdict.py

@@ -0,0 +1,201 @@
+"""findings.md headline-verdict derivation.
+
+:func:`_compute_findings_md_verdict` derives the
+findings.md headline (SHIP / NO-SHIP / ABORT) from the synth's consolidated
+findings + the test-leg outcome; the matrix mirrors
+:func:`syncade.orchestrator._compute_exit_code`'s test-leg branches so the two
+surfaces always agree about the overall run outcome.
+"""
+
+from __future__ import annotations
+
+from syncade.dispatcher import DispatchResult
+from syncade.synthesis import SynthesizerOutput, has_active_blocker
+from syncade.test_runner import TestRunResult
+
+
+def _compute_findings_md_verdict(
+    synth_output: SynthesizerOutput,
+    test_result: TestRunResult | None,
+    test_skip_reason: str | None = None,
+    blocking_check_results: list[TestRunResult] | None = None,
+    dispatch_result: DispatchResult | None = None,
+) -> tuple[str, str]:
+    """Derive the findings.md headline verdict from the synth's findings.
+
+    The result also depends on the test-leg
+    outcome, (when the leg was skipped) the skip reason, AND the
+    BLOCKING mechanical-check results.
+
+    Returns ``(label, qualifier)`` where ``label`` is the headline
+    ("SHIP", "NO-SHIP", "ABORT") and ``qualifier`` is the
+    parenthetical explaining where the verdict came from.
+
+    The matrix mirrors
+    :func:`syncade.orchestrator._compute_exit_code`'s test-leg +
+    blocking-check branches exactly so the two surfaces always agree
+    about the overall run outcome. The test leg and the blocking
+    checks share one "mechanical gate" bucket; ``subprocess_error``
+    (ABORT, exit 40) outranks BOTH a synth blocker and a ``failed``
+    gate (NO-SHIP, exit 30), matching ``_compute_exit_code``'s
+    ordering — a gate that couldn't run leaves the round
+    indeterminate regardless of what the synth found:
+
+    +-----------------+--------------------------+-----------+
+    | synth blocker?  | mechanical gate outcome  | verdict   |
+    +=================+==========================+===========+
+    | (any)           | any gate subprocess_err  | ABORT     |
+    | yes             | no gate subprocess_err   | NO-SHIP   |
+    | no              | any gate failed          | NO-SHIP   |
+    | no              | all gates passed/skipped | SHIP      |
+    +-----------------+--------------------------+-----------+
+
+    A "mechanical gate" is the test leg OR a ``blocking`` check.
+    ``advisory`` checks are never passed in (``blocking_check_results``
+    holds only blocking ones), so they are structurally unable to move
+    the verdict — exactly as they cannot reach ``_compute_exit_code``.
+    With no blocking checks the bucket is just the test leg:
+
+    +-----------------+----------------+----------------------+-----------+
+    | synth blocker?  | test outcome   | test_skip_reason     | verdict   |
+    +=================+================+======================+===========+
+    | yes (any)       | (skipped)      | (any)                | NO-SHIP   |
+    | no              | passed         | None                 | SHIP      |
+    | no              | failed         | None                 | NO-SHIP   |
+    | no              | subprocess_err | None                 | ABORT     |
+    | no              | None (skipped) | test_command_unset   | SHIP      |
+    | no              | None (skipped) | reviewer_failed *    | NO-SHIP   |
+    | no              | None (skipped) | synth_failed *       | NO-SHIP   |
+    | no              | None (skipped) | test_worktree_error  | ABORT     |
+    +-----------------+----------------+----------------------+-----------+
+
+    \\* These rows are theoretical — persist_findings_md is only
+    called on the synth-success-and-all-reviewers-succeeded path,
+    so test_skip_reason can practically only be
+    ``test_command_unset`` or ``test_worktree_error`` here. The
+    matrix rows are listed for completeness / future-proofing.
+
+    The "ABORT" wording for subprocess_error AND
+    ``test_worktree_error`` is intentional — both are
+    leg-couldn't-run states operationally distinct from "ship it"
+    AND from "don't ship it because of a real defect". The
+    operator's fix in both cases is environmental (PATH / binary
+    / config / git state), not code.
+    """
+    # Fold the test leg AND the blocking mechanical checks into one gate
+    # bucket, mirroring _compute_exit_code. subprocess_error (ABORT, exit 40)
+    # is the highest-precedence signal — a gate that couldn't run leaves the
+    # round indeterminate, so the operator fixes the environment first. With
+    # no blocking checks the bucket is just the test leg.
+    blocking = blocking_check_results or []
+    errored_checks = [c for c in blocking if c.outcome == "subprocess_error"]
+    failed_checks = [c for c in blocking if c.outcome == "failed"]
+
+    # ABORT — a mechanical gate couldn't run (its harness/binary broke). This
+    # is evaluated BEFORE the synth-blocker branch: checks run on synth-blocker
+    # rounds (the test leg does not), so a broken check harness can coincide
+    # with an active blocker, and an indeterminate gate outranks even NO-SHIP —
+    # exactly as _compute_exit_code maps a blocking subprocess_error to exit 40
+    # regardless of synth state. (test_result is None on blocker rounds, so its
+    # branch never fires there; the zero-checks ordering is unchanged.)
+    if test_result is not None and test_result.outcome == "subprocess_error":
+        return (
+            "ABORT",
+            "test re-run subprocess failed; verdict indeterminate until "
+            "the environment problem is fixed",
+        )
+    if errored_checks:
+        return (
+            "ABORT",
+            f"blocking check '{errored_checks[0].name}' subprocess failed; "
+            "verdict indeterminate until the environment problem is fixed",
+        )
+
+    # Synth blocker wins over a gate that ran (failed/passed) — the test leg
+    # is skipped on synth-blocker paths anyway (see _compute_exit_code), so
+    # test_result is None here and only checks can be present.
+    if has_active_blocker(synth_output):
+        return ("NO-SHIP", "mechanical, from consolidated_findings")
+
+    # test-worktree-error is operationally an ABORT,
+    # not a SHIP. The leg couldn't be provisioned, so the test
+    # signal is indeterminate. exit_code on the orchestrator side
+    # is 60 (WORKTREE_ERROR), not 0 — findings.md saying SHIP
+    # would directly contradict the exit code.
+    if test_skip_reason == "test_worktree_error":
+        return (
+            "ABORT",
+            "test re-run worktree could not be provisioned; verdict "
+            "indeterminate until the worktree provisioning failure "
+            "is fixed (exit 60)",
+        )
+
+    # NO-SHIP — a mechanical gate ran and failed.
+    if test_result is not None and test_result.outcome == "failed":
+        return (
+            "NO-SHIP",
+            f"mechanical, from test re-run exit {test_result.exit_code} (synthesizer was clean)",
+        )
+    if failed_checks:
+        return (
+            "NO-SHIP",
+            f"mechanical, from blocking check '{failed_checks[0].name}' exit "
+            f"{failed_checks[0].exit_code} (synthesizer was clean)",
+        )
+
+    # DECISION NEEDED — every gate is clean, but two or more distinct reviewers
+    # each raised a blocker and the synthesizer deactivated all of them
+    # (PR-h-01 increment D → exit 10). Printing SHIP here would contradict both
+    # the exit code and decision-needed.md, which says in as many words that the
+    # loop refused to report a SHIP it cannot justify. findings.md is the
+    # most-read artifact, so this is the surface where that contradiction does
+    # the most damage.
+    #
+    # This bug class has now regressed three times (T1.6 failed test leg, then
+    # failed blocking check, then this) for one reason: a new exit code was
+    # added without a matching branch here. If you add a fourth, add it here.
+    if _multi_reviewer_blockers_all_deactivated(dispatch_result):
+        return (
+            "DECISION NEEDED",
+            "2+ reviewers each raised a blocker and all were deactivated; "
+            "see decision-needed.md (exit 10)",
+        )
+
+    # SHIP — synth clean and every mechanical gate passed or was skipped.
+    if test_result is None:
+        # Test leg skipped — configured off (test_command_unset) OR a
+        # hypothetical reviewer/synth-failed path (which doesn't reach here in
+        # production but is listed in the matrix for completeness).
+        return ("SHIP", "mechanical, from consolidated_findings; test leg skipped")
+    # test_result.outcome == "passed".
+    return (
+        "SHIP",
+        "mechanical, from consolidated_findings + test re-run passed",
+    )
+
+
+def _multi_reviewer_blockers_all_deactivated(dispatch_result: DispatchResult | None) -> bool:
+    """Mirror of :func:`syncade.orchestrator.verdict._multi_reviewer_blockers_all_deactivated`
+    for the render surface.
+
+    Deliberately NOT imported from the orchestrator: ``persistence`` must not
+    depend on ``orchestrator`` (which imports persistence), and the predicate is
+    one set comprehension. The behavioural tie is enforced by test, not by a
+    shared import — see ``tests/persistence/test_findings_md_verdict.py``.
+
+    Callers reach this only after every gate is clean and
+    ``has_active_blocker`` is False, so "all deactivated" needs no separate
+    check, exactly as on the orchestrator side.
+    """
+    if dispatch_result is None:
+        return False
+    return (
+        len(
+            {
+                r.reviewer_name
+                for r in dispatch_result.successes
+                if r.output is not None and any(f.severity == "blocker" for f in r.output.findings)
+            }
+        )
+        >= 2
+    )

syncade/persistence/_markdown.py

@@ -0,0 +1,286 @@
+"""Markdown-rendering helpers shared across persistence write paths.
+
+These leaves of the dependency graph carry only narrow domain imports —
+``syncade.dispatcher`` (``ReviewerRunResult`` for :func:`_reviewer_file_links`,
+``DispatchResult`` for :func:`_consensus_lines`) and
+``syncade.synthesis.ConsolidatedFinding`` (for :func:`_consensus_lines`).
+Higher-level writers (``findings_md``, ``run_summary``) compose these into
+per-document layout.
+"""
+
+from __future__ import annotations
+
+from syncade.dispatcher import DispatchResult, ReviewerRunResult
+from syncade.synthesis import ConsolidatedFinding, distinct_reviewer_count
+
+
+def _md_inline_code(text: str) -> str:
+    """Render ``text`` as a markdown inline-code span.
+
+    Handles content that itself contains backticks.
+
+    The CommonMark inline-code-span rule: wrap the content with
+    a run of backticks one longer than any run of backticks in
+    the content. If the content begins or ends with a backtick
+    (or any whitespace at the edges of the content matters), pad
+    with a single space on each side.
+
+    Examples:
+    - ``hello`` → ``\\`hello\\```
+    - ``pytest --basetemp=\\`mktemp -d\\``` → ``\\`\\`pytest
+      --basetemp=\\`mktemp -d\\`\\`\\``` (double-backtick fence
+      surrounds the single-backtick content; outer spaces would
+      be needed only if content started/ended with a backtick).
+    - ``\\`leading-backtick`` → ``\\`\\` \\`leading-backtick \\`\\``
+
+    Why this helper exists: the operator's free-form
+    ``test_command`` can contain backticks for command
+    substitution (``$()`` is the modern form but backticks still
+    appear in legacy or terse configs). Rendering it with a
+    single-backtick markdown span would close the code span
+    inside the command, producing broken markdown that renders
+    half the operator's command as plain text.
+
+    : this helper is for SINGLE-LINE content only. Multi-
+    line content (operator's TOML triple-quoted commands) must
+    use :func:`_md_command_field` instead, which switches to a
+    fenced code block when newlines are present. Calling
+    ``_md_inline_code`` with newline content produces broken
+    markdown (the inline span doesn't allow newlines).
+    """
+    if not text:
+        # Empty span. Use a minimal valid form rather than emit
+        # ``"`"`` (which is an unclosed backtick).
+        return "``"
+    # Find the longest run of consecutive backticks in the text.
+    max_run = 0
+    current = 0
+    for ch in text:
+        if ch == "`":
+            current += 1
+            if current > max_run:
+                max_run = current
+        else:
+            current = 0
+    # Wrap with a fence one longer than the longest internal run.
+    fence = "`" * (max_run + 1)
+    # If the content starts or ends with a backtick, pad with a
+    # single space on each side so the fence doesn't touch the
+    # backtick (CommonMark would otherwise interpret the
+    # leading/trailing backtick as part of the fence).
+    pad = " " if (text.startswith("`") or text.endswith("`")) else ""
+    return f"{fence}{pad}{text}{pad}{fence}"
+
+
+def _md_command_lines(
+    command: str,
+    *,
+    prefix: str = "",
+    inline_suffix: str = "",
+) -> list[str]:
+    """Render an operator-configured ``test_command`` as
+    one or more markdown lines. Returns a list suitable for
+    ``lines.extend(...)``.
+
+    Two rendering forms based on whether ``command`` contains
+    newlines:
+
+    1. **Single-line** → ``[f"{prefix}**Command:** {inline}{inline_suffix}"]``
+       where ``inline`` is :func:`_md_inline_code`'s
+       backtick-safe span. ``inline_suffix`` is appended to the
+       end of the line (used for the findings.md trailing
+       two-space hard-break convention).
+    2. **Multi-line** → a fenced code block on its own
+       paragraph::
+
+           {prefix}**Command:**
+
+           ```sh
+           {command}
+           ```
+
+       The ``inline_suffix`` is intentionally NOT applied to the
+       multi-line form — fenced code blocks don't need a hard-
+       break suffix, and adding one would create a malformed line.
+       The fence length adapts to the longest internal run of
+       backticks so commands containing backtick-fenced
+       subshells still render correctly.
+
+    Args:
+        command: The test command string (possibly multi-line).
+        prefix: Leading text on the first line (e.g. ``"- "`` for
+            list-item context in summary.md; empty for the bare
+            findings.md Test Suite block).
+        inline_suffix: Trailing text appended to the single-line
+            form (e.g. ``"  "`` for markdown hard-break).
+            Ignored for the multi-line form.
+
+    Why this helper exists: TOML triple-quoted strings let
+    operators write multi-line test_commands (e.g. setup +
+    invocation, one-step-per-line for clarity). Rendering
+    multi-line content with the single-line ``**Command:**
+    \\`...\\``` form produces broken markdown — the inline span
+    doesn't accept newlines, so the second line drops out of the
+    code span and renders as paragraph text.
+    """
+    if "\n" not in command:
+        return [f"{prefix}**Command:** {_md_inline_code(command)}{inline_suffix}"]
+    # Multi-line: render as a fenced block. Fence length is one
+    # longer than the longest run of backticks in the content
+    # so any inner backticks pass through unchanged.
+    max_run = 0
+    current = 0
+    for ch in command:
+        if ch == "`":
+            current += 1
+            if current > max_run:
+                max_run = current
+        else:
+            current = 0
+    fence = "`" * max(3, max_run + 1)
+    return [
+        f"{prefix}**Command:**",
+        "",
+        f"{fence}sh",
+        command.rstrip("\n"),
+        fence,
+    ]
+
+
+def _file_or_repo_wide(file: str | None) -> str:
+    """Markdown for ``ConsolidatedFinding.file`` rendering — ``file``
+    as a code-span when present, ``"repo-wide"`` (no backticks) when
+    null. Matches the brief's ``findings.md`` layout."""
+    if file is None:
+        return "repo-wide"
+    return f"`{file}`"
+
+
+def _consensus_lines(
+    finding: ConsolidatedFinding,
+    dispatch_result: DispatchResult | None,
+) -> list[str]:
+    """the advisory per-finding reviewer-consensus line for findings.md.
+
+    Returns a single ``**Consensus:** N of M reviewers[ (unanimous)]`` line
+    (as a one-element list, for ``lines.extend``), or ``[]`` when
+    ``dispatch_result is None``.
+
+    - **N** = distinct ``reviewer_name``s in the finding's ``provenance`` —
+      how many reviewers actually raised this finding.
+    - **M** = reviewers in the run (``len(dispatch_result.results)``).
+    - ``M > 1 and N == M`` → append ``(unanimous)``; ``M == 1`` → the singular
+      noun "reviewer" (unanimity is only meaningful with more than one).
+
+    Advisory only: consensus is render-derived and never reaches
+    :func:`syncade.orchestrator._compute_exit_code` — the mechanical verdict is
+    untouched. Dismissed findings still render their consensus; it describes who
+    *raised* the finding, independent of the synthesizer's disposition.
+    """
+    if dispatch_result is None:
+        return []
+    m = len(dispatch_result.results)
+    n = distinct_reviewer_count(finding.provenance)
+    noun = "reviewer" if m == 1 else "reviewers"
+    line = f"**Consensus:** {n} of {m} {noun}"
+    if m > 1 and n == m:
+        line += " (unanimous)"
+    return [f"{line}  "]
+
+
+def _summary_needs_block_form(summary: str) -> bool:
+    """Decide whether to render ``summary`` inline or as its own block.
+
+    The reviewer template allows the ``summary`` field to be "one paragraph or a
+    short bulleted list". Inline rendering
+    (``**Summary:** the prose``) reads cleanly for one-paragraph
+    content, but produces malformed markdown when the summary starts
+    with a list marker (``- ran pytest`` becomes
+    ``**Summary:** - ran pytest`` — the ``-`` reads as inline text,
+    not a list bullet) or contains newlines (the second line and
+    onward render outside the bold marker's scope and can look
+    detached).
+
+    Block form is used when either holds:
+
+    - the summary contains a newline (multi-line content), OR
+    - the summary's first non-whitespace characters are a markdown
+      list marker (``- ``, ``* ``, or ``+ ``) — the reviewer
+      intentionally wrote a bulleted list.
+
+    Otherwise inline form is used.
+    """
+    if "\n" in summary:
+        return True
+    stripped_left = summary.lstrip()
+    return stripped_left.startswith(("- ", "* ", "+ "))
+
+
+def _format_summary_block(summary: str) -> list[str]:
+    """Render the ``**Summary:**`` block for one reviewer.
+
+    See :func:`_summary_needs_block_form` for the inline-vs-block
+    decision rule. Returns a list of lines suitable for
+    ``lines.extend(...)``. Inline form is one line; block form is
+    the header on its own line, then a blank line, then the summary
+    content (which may itself span multiple lines). Trailing
+    whitespace is never produced — the inline form ends with the
+    summary content directly; the block form's header line is bare.
+    """
+    if _summary_needs_block_form(summary):
+        return ["**Summary:**", "", summary]
+    return [f"**Summary:** {summary}"]
+
+
+def _format_string_list_block(header: str, items: list[str]) -> list[str]:
+    """Render a ``**header:**`` block for the narrative sections
+    in ``summary.md`` as a list of lines (no trailing whitespace).
+
+    - **Empty list** renders inline as a single line ending with
+      ``None.``::
+
+          **Coverage gaps:** None.
+
+      Brief calls this out by name: empty lists should read as
+      ``None`` for cleaner human reading, not as an empty bullet.
+    - **Non-empty list** renders the header on its own line, then a
+      blank line, then a markdown bulleted list, one item per line.
+      The header line has NO trailing whitespace (fix #3 from the
+      QA round)::
+
+          **Coverage gaps:**
+
+          - did not exercise the staging Postgres
+          - skipped playwright on mobile breakpoints
+
+    Returns a list of lines suitable for the caller's
+    ``lines.extend(...)`` — the caller is responsible for joining
+    with ``\\n`` at the end. Returning a list (rather than a single
+    string) is what makes the no-trailing-whitespace guarantee
+    achievable: a single-string formulation forces the header onto
+    the same return as the first content line, and the seam between
+    them needs whitespace one way or the other.
+    """
+    if not items:
+        return [f"**{header}:** None."]
+    return [f"**{header}:**", "", *(f"- {item}" for item in items)]
+
+
+def _reviewer_file_links(run_result: ReviewerRunResult) -> str:
+    """Build the ``[.ext](file)`` link list for one reviewer, including
+    only the per-reviewer files :func:`persist_reviewer_result` actually
+    writes for that outcome.
+
+    ``.stdout`` / ``.stderr`` are always written. A success additionally
+    writes ``.parsed.json``; a failure additionally writes
+    ``.error.txt``. Deriving the list from the outcome — rather than
+    probing the filesystem — keeps this independent of call ordering and
+    free of dangling links.
+    """
+    name = run_result.reviewer_name
+    suffixes = [".stdout", ".stderr"]
+    if run_result.output is not None:
+        suffixes.insert(0, ".parsed.json")
+    if run_result.error is not None:
+        suffixes.append(".error.txt")
+    return " | ".join(f"[{suffix}]({name}{suffix})" for suffix in suffixes)

syncade/persistence/_validation.py

@@ -0,0 +1,37 @@
+"""Reviewer-name validation shared across persistence write paths.
+
+Reviewer names are validated against a basename rule in
+``WorktreeManager._validate_reviewer_name``; that rule guarantees
+``<round_dir> / <reviewer_name>`` stays under ``round_dir``. Persistence
+applies the same rule defensively in case a caller bypasses the
+worktree manager.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+_FORBIDDEN_NAME_CHARS = ("/", "\\")
+
+
+def _validate_reviewer_filename_basename(name: str) -> None:
+    """Refuse a name that would let the persistence path escape
+    ``round_dir``.
+
+    The worktree manager already enforces this for the per-reviewer
+    directory under ``/tmp/syncade/``; we re-validate here so a caller
+    that constructs a :class:`ReviewerRunResult` directly (no worktree
+    involved) can't trick persistence into writing outside the run
+    directory.
+    """
+    if (
+        not name
+        or name in (".", "..")
+        or any(c in name for c in _FORBIDDEN_NAME_CHARS)
+        or Path(name).is_absolute()
+    ):
+        raise ValueError(
+            f"reviewer name {name!r} cannot be used as a persistence "
+            f"basename (must be a plain basename, no separators, parent "
+            f"refs, or absolute paths)"
+        )