code-mower 0.5.0b5__py3-none-any.whl

code_mower/trailer_comment_labeler.py

@@ -0,0 +1,207 @@
+#!/usr/bin/env python3
+"""Generic labeler for trailer-comment audit lanes.
+
+Codex, Devin, and Local LLM audit comments all use the same state machine:
+trusted comment author -> final verdict trailer/prose -> reviewed head check ->
+terminal or needs label. Lane-specific values live in tools/lane_configs/.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+from pathlib import Path
+from typing import Any, Dict, Optional, Sequence
+
+if __package__ and __package__.startswith("code_mower"):
+    from .audit_labeler_lib import (
+        LaneConfig,
+        LabelDecision,
+        apply_label_decision,
+        extract_reviewed_sha,
+        fetch_pull_request,
+        load_json,
+        sha_matches_reviewed_head,
+    )
+    from .lane_configs import load_lane_config
+else:
+    try:
+        from tools.audit_labeler_lib import (
+            LaneConfig,
+            LabelDecision,
+            apply_label_decision,
+            extract_reviewed_sha,
+            fetch_pull_request,
+            load_json,
+            sha_matches_reviewed_head,
+        )
+        from tools.lane_configs import load_lane_config
+    except ImportError:  # pragma: no cover - direct `python tools/foo.py` execution
+        from audit_labeler_lib import (
+            LaneConfig,
+            LabelDecision,
+            apply_label_decision,
+            extract_reviewed_sha,
+            fetch_pull_request,
+            load_json,
+            sha_matches_reviewed_head,
+        )
+        from lane_configs import load_lane_config
+
+
+HEAD_CHANGED_PATTERN = re.compile(
+    r"HEAD_CHANGED_DURING_REVIEW\s*:\s*reviewed\b",
+    flags=re.IGNORECASE,
+)
+
+
+def classify_audit_comment(body: str, config: LaneConfig) -> Optional[str]:
+    """Return "done", "blocked", "needs", or None for a lane comment body."""
+    trailers = list(config.trailer_pattern().finditer(body))
+    if trailers:
+        label = trailers[-1].group(1).lower()
+        if label == config.done_label:
+            return "done"
+        if label == config.blocked_label:
+            return "blocked"
+        return "needs"
+
+    if HEAD_CHANGED_PATTERN.search(body):
+        return "needs"
+
+    if any(pattern.search(body) for pattern in config.pass_patterns):
+        return "done"
+    if config.label_state_fallbacks and _has_label_fallback(body, config.done_label):
+        return "done"
+
+    if any(pattern.search(body) for pattern in config.blocked_patterns):
+        return "blocked"
+    if config.label_state_fallbacks and _has_label_fallback(body, config.blocked_label):
+        return "blocked"
+
+    return None
+
+
+def _has_label_fallback(body: str, label: str) -> bool:
+    escaped = re.escape(label)
+    return bool(
+        re.search(
+            rf"\**(?:Intended\s+|Expected\s+)?Label state:\**\s*`?\b{escaped}\b",
+            body,
+            flags=re.IGNORECASE,
+        )
+        or re.search(
+            rf"(?:Intended|Expected)\s+labels?:\s*(?:add\s+)?`?\b{escaped}\b",
+            body,
+            flags=re.IGNORECASE,
+        )
+    )
+
+
+def resolve_label_decision(
+    event: Dict[str, Any],
+    *,
+    current_head_sha: Optional[str],
+    config: LaneConfig,
+) -> tuple[Optional[LabelDecision], str]:
+    if event.get("action") != "created":
+        return None, f"unsupported action: {event.get('action')}"
+
+    issue = event.get("issue") or {}
+    if "pull_request" not in issue:
+        return None, "comment is not on a pull request"
+
+    comment = event.get("comment") or {}
+    author = (comment.get("user") or {}).get("login", "")
+    if author.lower() not in config.comment_authors():
+        return None, f"ignored comment author: {author}"
+
+    body = comment.get("body") or ""
+    status = classify_audit_comment(body, config)
+    if status is None:
+        return None, f"comment is not a final {config.display_name} audit result"
+
+    issue_number = int(issue["number"])
+    reviewed_sha = extract_reviewed_sha(body)
+    if status != "needs" and not reviewed_sha:
+        return None, "audit result is missing Head SHA"
+    if reviewed_sha and current_head_sha and not sha_matches_reviewed_head(reviewed_sha, current_head_sha):
+        return LabelDecision(
+            issue_number=issue_number,
+            add_label=config.needs_label,
+            remove_labels=(config.done_label, config.blocked_label),
+            reviewed_sha=reviewed_sha,
+            reason=f"reviewed SHA {reviewed_sha} does not match current head {current_head_sha}",
+        ), "label needs audit"
+
+    if status == "needs":
+        return LabelDecision(
+            issue_number=issue_number,
+            add_label=config.needs_label,
+            remove_labels=(config.done_label, config.blocked_label),
+            reviewed_sha=reviewed_sha,
+            reason="audit reported head changed during review",
+        ), "label needs audit"
+
+    if status == "done":
+        return LabelDecision(
+            issue_number=issue_number,
+            add_label=config.done_label,
+            remove_labels=(config.needs_label, config.blocked_label),
+            reviewed_sha=reviewed_sha,
+            reason="audit passed",
+        ), "label done"
+
+    return LabelDecision(
+        issue_number=issue_number,
+        add_label=config.blocked_label,
+        remove_labels=(config.needs_label, config.done_label),
+        reviewed_sha=reviewed_sha,
+        reason="audit blocked or incomplete",
+    ), "label blocked"
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--lane", required=True, help="Trailer audit lane from tools/lane_configs/.")
+    args = parser.parse_args(argv)
+    config = load_lane_config(args.lane)
+
+    event_path = Path(os.environ["GITHUB_EVENT_PATH"])
+    repo = os.environ["GITHUB_REPOSITORY"]
+    event = load_json(event_path)
+
+    current_head_sha = os.environ.get("DRY_RUN_HEAD_SHA")
+    tokens = config.github_tokens_from_env()
+    if not os.environ.get("DRY_RUN"):
+        if not tokens:
+            token_names = " or ".join(config.token_env_vars)
+            print(f"error: {token_names} is required", file=sys.stderr)
+            return 1
+        issue = event.get("issue") or {}
+        issue_number = int(issue.get("number", 0))
+        if issue_number and "pull_request" in issue:
+            current_head_sha = fetch_pull_request(repo, issue_number, tokens=tokens)["head"]["sha"]
+
+    decision, reason = resolve_label_decision(event, current_head_sha=current_head_sha, config=config)
+    if decision is None:
+        print(f"skip: {reason}")
+        return 0
+
+    if os.environ.get("DRY_RUN"):
+        print(json.dumps({"decision": decision.__dict__, "reason": reason}, sort_keys=True))
+        return 0
+
+    apply_label_decision(repo, decision, tokens=tokens)
+    print(
+        f"applied: add {decision.add_label}; remove {', '.join(decision.remove_labels)} "
+        f"on {repo}#{decision.issue_number} ({decision.reason})"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

code_mower/versioning.py

@@ -0,0 +1,32 @@
+"""Version and public package-spec helpers."""
+
+from __future__ import annotations
+
+import re
+
+
+PUBLIC_REPO_URL = "https://github.com/codemower-ai/code-mower"
+STAGE_TAG_NAMES = {
+    "a": "alpha",
+    "b": "beta",
+    "rc": "rc",
+}
+
+
+def release_tag_for_version(version: str) -> str:
+    match = re.fullmatch(
+        r"(?P<base>\d+\.\d+\.\d+)(?:(?P<stage>a|b|rc)(?P<num>\d+))?",
+        version,
+    )
+    if not match:
+        return f"v{version}"
+    base = match.group("base")
+    stage = match.group("stage")
+    number = match.group("num")
+    if not stage or not number:
+        return f"v{base}"
+    return f"v{base}-{STAGE_TAG_NAMES[stage]}.{number}"
+
+
+def public_package_spec(version: str, repo_url: str = PUBLIC_REPO_URL) -> str:
+    return f"git+{repo_url}.git@{release_tag_for_version(version)}"

code_mower-0.5.0b5.dist-info/METADATA

@@ -0,0 +1,302 @@
+Metadata-Version: 2.4
+Name: code-mower
+Version: 0.5.0b5
+Summary: Multi-reviewer AI code audit orchestration
+License-Expression: Apache-2.0
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: PyYAML>=6.0
+Dynamic: license-file
+
+# Code Mower
+
+Code Mower helps teams set up AI peer-programmer and reviewer lanes on real
+GitHub pull requests, then measure which builders and reviewers are useful on
+their actual codebase.
+
+The short version:
+
+- create safe, manual-first reviewer lanes for Codex, Claude, Gitar, and other
+  AI review tools;
+- run setup diagnostics before a lane can surprise you with spend, source
+  exposure, or GitHub Actions churn;
+- generate local reviewer value reports from known-clean and known-blocked PRs;
+  and
+- optionally share sanitized metadata with [CodeMower.com](https://codemower.com)
+  for private team dashboards today and aggregate benchmarks as that dataset
+  becomes useful.
+
+Code Mower is local-first. The OSS tool works without the hosted service.
+Default cloud bundles exclude source code, raw diffs, raw model transcripts,
+raw stdout/stderr, auth output, and secrets.
+
+## Design Principles
+
+Code Mower should feel like an engineering tool, not a demo harness:
+
+- **Local first:** install, diagnose, audit, and report without a hosted
+  account.
+- **Manual first:** new reviewer lanes start explicit and observable before
+  they can affect merge policy.
+- **Evidence first:** promote lanes from real calibration data on your
+  repository, not from generic benchmark claims.
+- **Privacy first:** cloud sharing is opt-in metadata by default, with source,
+  diffs, transcripts, auth output, and secrets excluded.
+- **Composable by design:** providers, lenses, context packs, calibration, and
+  cloud upload stay separate so teams can adopt only the parts they trust.
+
+## What It Looks Like
+
+`code-mower doctor --preflight` is the first useful command. It checks your
+runtime, GitHub setup, provider CLIs, token posture, optional cloud setup, and
+private-repo Actions cost traps. `--preflight` is the friendly name for the
+versioned v0.5 first-run preset, so `doctor --v05` remains equivalent for
+scripts.
+
+Example, shortened:
+
+```text
+$ code-mower doctor --preflight
+PASS  config.validate             config validates
+PASS  profile.select              selected profile: codex, claude_audit, gitar
+PASS  runtime.python              Python 3.12 satisfies Code Mower requirements
+PASS  runtime.github_auth         GitHub CLI auth probe succeeded
+PASS  runtime.local_cli codex     codex found
+PASS  runtime.local_cli claude    claude auth smoke probe succeeded
+WARN  env.tokens codex            missing CODEX_AUDIT_LABEL_TOKEN or GITHUB_TOKEN
+WARN  github.actions_cost         private repo has high-frequency metadata workflows
+PASS  cloud.token                 optional Code Mower Cloud token file is configured
+
+Summary: warn, 20 checks, 0 failures, 5 warnings
+Next: fix token warnings, keep paid lanes manual, then generate a value report.
+```
+
+The warnings are the point: Code Mower should make setup, cost, and trust
+boundaries visible before you promote any reviewer lane.
+
+See a fuller static transcript: [docs/first-run-transcript.md](docs/first-run-transcript.md).
+
+## See The Value Shape First
+
+If you want to understand the product before installing anything, start with
+the checked-in demo calibration package:
+
+- [examples/demo-calibration/README.md](examples/demo-calibration/README.md)
+- [examples/demo-calibration/reviewer-value-report.md](examples/demo-calibration/reviewer-value-report.md)
+- [docs/first-user-demo-transcript.md](docs/first-user-demo-transcript.md)
+
+The example is intentionally tiny and synthetic: one known-clean control, one
+known-blocked control, and three reviewer lanes. It shows the decision Code
+Mower is built to support: which AI reviewers are useful, noisy, expensive,
+fast, or eligible for stronger merge policy on your actual codebase.
+
+## Try It First
+
+Code Mower currently targets Python 3.11+; Python 3.12 is recommended.
+
+```bash
+python3.12 --version
+pipx install --python python3.12 "git+https://github.com/codemower-ai/code-mower.git@v0.5.0-beta.5"
+code-mower --version
+```
+
+From the repository you want to pilot:
+
+```bash
+code-mower init --easy
+code-mower doctor --preflight
+code-mower checks detect --json
+```
+
+When those look sane, write the generated setup to a reviewable folder and
+produce the starter local report:
+
+```bash
+code-mower init --easy --apply --output-dir .code-mower.generated
+code-mower calibration value-report .code-mower.generated/calibration-corpus.json \
+  --output .code-mower/reviewer-value-report.md
+```
+
+The generated starter corpus proves the command path. To bootstrap a draft from
+your repository history:
+
+```bash
+code-mower calibration auto-discover \
+  --repo OWNER/REPO \
+  --last-n 20 \
+  --output .code-mower/draft-calibration-corpus.json
+```
+
+Auto-discovery uses recent merged PR metadata, structured audit trailers, and
+review-request signals to propose known-clean and known-blocked cases. Review
+every disposition before using it for lane promotion or merge policy.
+
+Full walkthrough: [docs/try-in-10-minutes.md](docs/try-in-10-minutes.md).
+First-time command map: [docs/launch-command-surface.md](docs/launch-command-surface.md).
+
+## Why Not Just Run Codex Or Claude Yourself?
+
+You should, at first. Code Mower is not a replacement for a good local agent or
+reviewer CLI.
+
+Code Mower adds the operating layer around those tools:
+
+- consistent reviewer lanes on real pull requests;
+- setup checks for auth, Python, GitHub permissions, private-repo Actions cost,
+  provider CLIs, and cloud-token posture;
+- calibration against known-clean and known-blocked PRs instead of vibes;
+- evidence-gated lane promotion: informational, selective, or merge-gating;
+- spend/latency/usefulness reporting across providers and lenses; and
+- privacy boundaries for optional metadata sharing.
+
+The goal is to learn which AI builders and reviewers are worth trusting on your
+actual codebase, at what cost, and under which merge policy.
+
+## Optional Cloud Sharing
+
+Code Mower Cloud currently provides private team dashboards from opt-in
+metadata. Cross-team cohort benchmarking is a roadmap feature that becomes
+valuable only as enough teams contribute sanitized data. The local OSS path
+stays useful without the hosted service.
+
+The cloud value loop is:
+
+1. run local Code Mower reports;
+2. inspect the metadata-only bundle or dogfood preview;
+3. upload only with `--yes`; and
+4. use [CodeMower.com](https://codemower.com) to see repo rollups, provider/lens
+   signal, cost/latency, noisy lanes, and next-lane recommendations over time.
+
+Start with a dry run:
+
+```bash
+code-mower cloud dogfood --json
+```
+
+Nothing uploads unless you pass `--yes`.
+
+To connect to [CodeMower.com](https://codemower.com), sign in at
+[https://codemower.com/login](https://codemower.com/login), create or receive a
+team token, then run:
+
+```bash
+code-mower cloud setup \
+  --token-stdin \
+  --team-id "YOUR_TEAM_SLUG" \
+  --install-id "your-laptop" \
+  --out ~/.config/code-mower/tokens/your-laptop.env
+```
+
+Cloud sharing details, historical catch-up, and repo-sync commands live in
+[docs/cloud-sharing.md](docs/cloud-sharing.md).
+
+## Provider Posture
+
+The first recommended lanes are local/manual:
+
+| Lane | Default role | Merge posture |
+| --- | --- | --- |
+| Codex audit | structured local peer audit | merge-gating eligible after setup |
+| Claude audit | structured local peer audit | merge-gating eligible after setup |
+| Gitar | advisory third signal | informational until calibrated |
+
+Everything else starts manual or informational until your own calibration data
+proves it is useful: Antigravity/Gemini, Hermes, CodeRabbit CLI, Cursor BugBot,
+Qodo, Greptile, Devin, local LLMs, and future ACP bridges.
+
+Provider details: [docs/provider-matrix.md](docs/provider-matrix.md).
+Setup/auth fixes: [docs/troubleshooting.md](docs/troubleshooting.md).
+
+## Road To v1.0
+
+The v1.0 bar is not "every provider works." The v1.0 bar is that a fresh senior
+engineer can:
+
+1. install Code Mower in a clean repo;
+2. understand the local/cloud trust boundary;
+3. run `init --easy` and `doctor --preflight`;
+4. detect and run the repo's native lint/test/build surface instead of assuming
+   every project uses the same tools;
+5. produce a local value report from known PR outcomes;
+6. decide which lanes should stay informational, selective, or merge-gating;
+   and
+7. optionally upload sanitized metadata to CodeMower.com and see useful team
+   dashboard signal.
+
+Future builder/orchestrator experiments extend the same loop from "who reviews
+best?" to "which AI builder plus reviewer loop ships best on this product?" See
+[docs/builder-experiments.md](docs/builder-experiments.md) and
+[docs/authoring-intelligence.md](docs/authoring-intelligence.md).
+
+## Installation Status
+
+The current public beta is `v0.5.0-beta.5` from
+[codemower-ai/code-mower](https://github.com/codemower-ai/code-mower). PyPI
+distribution builds now run from GitHub Releases. Publishing to PyPI remains
+off by default until trusted publishing is configured, so use the tagged GitHub
+install command above for this beta.
+
+For source checkout development and release rehearsal, use:
+
+```bash
+scripts/dev-python
+scripts/dev-python -m venv .venv
+.venv/bin/python -m pip install -e . ruff
+```
+
+The wrapper resolves Python 3.12+ and refuses stale or old system Python shims.
+
+## Known Limitations
+
+- PyPI distribution builds exist, but publishing is gated until trusted
+  publishing is configured; use the tagged GitHub install command. See
+  [docs/pypi-release.md](docs/pypi-release.md) for the TestPyPI/PyPI
+  activation path.
+- GitHub is the primary supported forge. GitLab, Bitbucket, and ACP bridges are
+  roadmap items.
+- Hosted/SaaS reviewers start informational or manual until calibration data
+  supports promotion.
+- `calibration auto-discover` is a bootstrap tool, not an adjudicator. It
+  proposes a draft corpus from PR history; humans still confirm the ground truth.
+- CodeMower.com currently provides private team dashboards; cohort benchmarks
+  are roadmap work and should not be treated as live product value yet.
+- Self-service cloud data deletion/export basics are live. Retention remains
+  conservative and team-controlled while automated retention jobs are roadmap
+  work.
+- Advanced/provider/operator commands remain available behind
+  `code-mower --help-all`. The default help path stays focused on `init`,
+  `doctor`, calibration, value reports, and optional cloud export/upload.
+
+## Docs Map
+
+- [Try Code Mower In 10 Minutes](docs/try-in-10-minutes.md)
+- [Quickstart](docs/quickstart.md)
+- [First Run Transcript](docs/first-run-transcript.md)
+- [First-User Demo Transcript](docs/first-user-demo-transcript.md)
+- [First-User Install Rehearsal](docs/first-user-install-rehearsal.md)
+- [Launch Command Surface](docs/launch-command-surface.md)
+- [Demo Calibration Example](examples/demo-calibration/README.md)
+- [PyPI Release Runbook](docs/pypi-release.md)
+- [Sample Doctor Output](docs/sample-doctor-output.md)
+- [Architecture](docs/architecture.md)
+- [Provider Matrix](docs/provider-matrix.md)
+- [GitHub Setup](docs/github-setup.md)
+- [Cloud Sharing](docs/cloud-sharing.md)
+- [Cloud Data Contract](docs/cloud-data-contract.md)
+- [Privacy And Threat Model](docs/privacy-threat-model.md)
+- [Current State And Roadmap](docs/current-state-and-roadmap.md)
+- [Public Release Checklist](docs/public-release-checklist.md)
+- [Changelog](CHANGELOG.md)
+- [Contributing](CONTRIBUTING.md)
+- [Support](SUPPORT.md)
+- [Security Policy](SECURITY.md)
+- [Code of Conduct](CODE_OF_CONDUCT.md)
+
+## License
+
+The Code Mower open-source core is licensed under Apache-2.0. Hosted
+benchmarking and reporting, managed integrations, private telemetry and
+benchmark data products, enterprise controls, and support are commercial
+surfaces unless licensed otherwise.