pi-dev-team 0.2.0

package/scripts/plan_gherkin_export.py

@@ -0,0 +1,227 @@
+#!/usr/bin/env python3
+"""plan_gherkin_export.py — export an approved plan's slice Gherkin to .feature files.
+
+Reads the plan's `**Gherkin persistence**:` metadata line and each
+`### Slice N:` section's fenced Gherkin block, and writes
+`<dir>/<plan-slug>/slice-<N>-<slice-slug>.feature` — byte-for-byte identical
+to the fenced block, modulo exactly one trailing newline, with no added
+header. plan-slug is the plan filename stem verbatim; slice-slug is the
+slice title lowercased with each run of non-alphanumeric characters
+collapsed to a single hyphen, leading/trailing hyphens trimmed.
+
+Uses `scripts/lib/plan_parse.py` for the slice-walking stage.
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from collections.abc import Iterable
+from pathlib import Path
+from typing import NamedTuple
+
+_HERE = Path(__file__).resolve().parent
+sys.path.insert(0, str(_HERE / "lib"))
+
+import plan_parse
+
+_PERSISTENCE_RE = re.compile(r"^\*\*Gherkin persistence\*\*\s*:\s*(.*)$")
+_SECTION_HEADING_RE = re.compile(r"^##\s")
+_NON_ALNUM_RE = re.compile(r"[^a-z0-9]+")
+
+PLAN_FILE_ONLY = "plan-file-only"
+
+
+class ExportError(Exception):
+    """Fatal export failure; the message names the offending path."""
+
+
+def _first_non_directory(path: Path) -> Path | None:
+    """Return the deepest existing segment of `path` that is not a directory."""
+    for candidate in (path, *path.parents):
+        if candidate.exists():
+            return None if candidate.is_dir() else candidate
+    return None
+
+
+def slugify(title: str) -> str:
+    """Lowercase; collapse non-alphanumeric runs to one hyphen; trim hyphens."""
+    return _NON_ALNUM_RE.sub("-", title.lower()).strip("-")
+
+
+def read_persistence_decision(lines: Iterable[str]) -> str | None:
+    """Return the metadata block's Gherkin persistence value, or None.
+
+    Only the metadata block (lines before the first `## ` section heading)
+    is scanned, so prose mentions of the marker elsewhere never match.
+    """
+    for raw in lines:
+        line = raw.rstrip("\n")
+        if _SECTION_HEADING_RE.match(line):
+            return None
+        match = _PERSISTENCE_RE.match(line)
+        if match:
+            value = match.group(1).replace("`", "").strip()
+            return value or None
+    return None
+
+
+def resolve_destination(decision: str) -> str | None:
+    """Map a recorded decision to a destination directory.
+
+    `plan-file-only` maps to None (nothing to export); a `custom: <path>`
+    value maps to its path; anything else is the destination directory
+    itself. Trailing slashes are dropped.
+    """
+    if decision == PLAN_FILE_ONLY:
+        return None
+    if decision.lower().startswith("custom:"):
+        decision = decision.split(":", 1)[1].strip()
+    return decision.rstrip("/") or None
+
+
+def _resolve_target_dir(destination: str, plan_slug: str, root: Path) -> Path:
+    """Validate the destination and return the tool-owned directory.
+
+    The exporter defends itself regardless of what the skill prose
+    validated: the recorded destination must stay inside `root` (no absolute
+    paths, no `..`, no symlink escape), and the tool-owned directory itself
+    must not be a symlink — it is about to be purged of `*.feature` files.
+    """
+    dest_path = Path(destination)
+    if dest_path.is_absolute() or ".." in dest_path.parts:
+        raise ExportError(
+            f"destination escapes the project root: {destination}"
+        )
+    target_dir = root / dest_path / plan_slug
+    resolved_root = root.resolve()
+    resolved_target = target_dir.resolve()
+    if resolved_root != resolved_target and resolved_root not in (
+        resolved_target.parents
+    ):
+        raise ExportError(
+            f"destination escapes the project root: {destination}"
+        )
+    if target_dir.is_symlink():
+        raise ExportError(
+            "tool-owned directory is a symlink, refusing to purge through it: "
+            f"{target_dir}"
+        )
+    collision = _first_non_directory(target_dir)
+    if collision is not None:
+        raise ExportError(
+            f"destination path collides with a non-directory file: {collision}"
+        )
+    return target_dir
+
+
+def _collect_features(lines: list[str]) -> tuple[list[tuple[str, str]], list[str]]:
+    """Return `(features, skipped)`: exportable `(filename, gherkin)` pairs
+    and the ids of slices with no gherkin block. Ids get the same slug
+    treatment as titles so a filename is always a single path component."""
+    blocks = plan_parse.slice_gherkin_blocks(lines)
+    features = [
+        (f"slice-{slugify(slice_id)}-{slugify(title)}.feature", gherkin)
+        for slice_id, title, gherkin in blocks
+        if gherkin is not None
+    ]
+    skipped = [slice_id for slice_id, _, gherkin in blocks if gherkin is None]
+    return features, skipped
+
+
+def _sync_feature_dir(
+    target_dir: Path, features: list[tuple[str, str]]
+) -> tuple[int, list[str]]:
+    """Clear the tool-owned dir of regular `*.feature` files and write the
+    current set; return `(overwritten_count, stale_names_removed)`."""
+    existing = (
+        sorted(
+            p
+            for p in target_dir.glob("*.feature")
+            if p.is_file() or p.is_symlink()
+        )
+        if target_dir.is_dir()
+        else []
+    )
+    new_names = {name for name, _ in features}
+    overwritten = sum(1 for p in existing if p.name in new_names)
+    stale = [p.name for p in existing if p.name not in new_names]
+    for path in existing:
+        # Unlinking a symlink removes the link, never its target. A file
+        # already gone is the desired post-state; tolerate races.
+        path.unlink(missing_ok=True)
+    target_dir.mkdir(parents=True, exist_ok=True)
+    for name, gherkin in features:
+        path = target_dir / name
+        if path.is_symlink():
+            # Never write through a planted link — writes stay inside root.
+            path.unlink()
+        # write_bytes keeps the content byte-for-byte (no newline translation)
+        path.write_bytes(gherkin.encode("utf-8"))
+    return overwritten, stale
+
+
+class _ExportOutcome(NamedTuple):
+    features: list[tuple[str, str]]
+    skipped: list[str]
+    overwritten: int
+    stale: list[str]
+
+
+def _build_report(destination: str, plan_slug: str, outcome: _ExportOutcome) -> list[str]:
+    report = [f"destination: {destination}/{plan_slug}"]
+    for name, _ in outcome.features:
+        report.append(f"wrote: {destination}/{plan_slug}/{name}")
+    for name in outcome.stale:
+        report.append(f"removed stale: {destination}/{plan_slug}/{name}")
+    for slice_id in outcome.skipped:
+        report.append(f"skipped (no gherkin block): slice {slice_id}")
+    report.append(
+        f"files written: {len(outcome.features)}, overwritten: {outcome.overwritten}, stale removed: {len(outcome.stale)}"
+    )
+    return report
+
+
+def export_plan(plan_path: Path, root: Path) -> list[str]:
+    """Export the plan's slice Gherkin blocks under `root`; return report lines."""
+    try:
+        text = plan_path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise ExportError(f"cannot read plan file: {plan_path}") from exc
+    lines = text.split("\n")
+
+    decision = read_persistence_decision(lines)
+    if decision is None:
+        return ["nothing to export: no Gherkin persistence decision recorded"]
+    destination = resolve_destination(decision)
+    if destination is None:
+        return ["nothing to export: Gherkin persistence is plan-file-only"]
+
+    plan_slug = plan_path.stem
+    target_dir = _resolve_target_dir(destination, plan_slug, root)
+    features, skipped = _collect_features(lines)
+    overwritten, stale = _sync_feature_dir(target_dir, features)
+    outcome = _ExportOutcome(features, skipped, overwritten, stale)
+    return _build_report(destination, plan_slug, outcome)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="plan_gherkin_export.py",
+        description="Export an approved plan's slice Gherkin blocks to .feature files.",
+    )
+    parser.add_argument("plan", type=Path, help="Path to the plan markdown file")
+    args = parser.parse_args(argv)
+    try:
+        report = export_plan(args.plan, Path.cwd())
+    except ExportError as exc:
+        sys.stderr.write(f"plan-gherkin-export: {exc}\n")
+        return 2
+    for line in report:
+        print(line)
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

package/scripts/plan_waves.py

@@ -0,0 +1,208 @@
+#!/usr/bin/env python3
+"""plan_waves.py — compute parallel build waves from a plan's slice DAG.
+
+Python port of `scripts/plan-waves.sh` (#589 / #572 Phase 2 Cluster E1).
+
+Parses each slice's `Depends-on`, topologically layers the DAG into waves
+(wave 1 = slices with no prerequisites), detects same-wave file collisions,
+and emits a stable JSON contract (schema `plan-waves/v1`) on stdout:
+
+    { "schema", "waves": [[id,...],...],
+      "slices": {id:{depends_on,files,wave}},
+      "collisions": [{wave, slices:[a,b], file}] }
+
+Rejects (exit 2, message on stderr):
+  - a dependency cycle
+  - a slice missing its Depends-on declaration
+  - an unknown dependency reference
+
+Uses `scripts/lib/plan_parse.py` for the parser stage.
+"""
+
+from __future__ import annotations
+
+import argparse
+import fnmatch
+import json
+import re
+import sys
+from pathlib import Path
+
+_HERE = Path(__file__).resolve().parent
+sys.path.insert(0, str(_HERE / "lib"))
+
+import plan_parse
+
+_TOKEN_SPLIT_RE = re.compile(r"[,\s]+")
+
+
+def _die(message: str) -> None:
+    sys.stderr.write("plan-waves: " + message + "\n")
+    sys.exit(2)
+
+
+def _is_glob(pattern: str) -> bool:
+    return any(ch in pattern for ch in "*?[")
+
+
+def _file_covered(file_path: str, patterns: list[str]) -> bool:
+    """True when `file_path` exactly matches a declared pattern, or a
+    declared glob pattern (fnmatch, stdlib — #865 AC9) matches it."""
+    for pattern in patterns:
+        if pattern == file_path:
+            return True
+        if _is_glob(pattern) and fnmatch.fnmatch(file_path, pattern):
+            return True
+    return False
+
+
+def _pattern_covers_any(pattern: str, files: list[str]) -> bool:
+    """True when a declared `pattern` is satisfied by at least one inferred
+    file — an exact-match hit, or (for a glob pattern) any fnmatch hit."""
+    for file_path in files:
+        if pattern == file_path:
+            return True
+        if _is_glob(pattern) and fnmatch.fnmatch(file_path, pattern):
+            return True
+    return False
+
+
+def _scope_mismatch(sid: str, declared: list[str], inferred: list[str]) -> dict:
+    """Return a `scope_mismatches` entry for `sid`, or `None` when the
+    declared and inferred sets reconcile (#865 AC3). `under_declared` is the
+    dangerous direction: a step plans to touch a file the slice never
+    declared. `over_declared` is a declared path/pattern nothing inferred
+    actually touches."""
+    under_declared = sorted(f for f in inferred if not _file_covered(f, declared))
+    over_declared = sorted(p for p in declared if not _pattern_covers_any(p, inferred))
+    if not under_declared and not over_declared:
+        return None
+    return {
+        "slice": sid,
+        "declared": sorted(declared),
+        "inferred": sorted(inferred),
+        "under_declared": under_declared,
+        "over_declared": over_declared,
+    }
+
+
+def compute_waves(plan_path: Path) -> dict:
+    """Return the plan-waves/v1 JSON payload for `plan_path`."""
+    plan_lines = plan_path.read_text().splitlines()
+    rows = plan_parse.parse_slices(plan_lines)
+    inferred_by_slice = plan_parse.step_files_union(plan_lines)
+
+    slices: dict[str, dict] = {}
+    order: list[str] = []
+    for sid, deps_raw, files_raw in rows:
+        files = [f for f in _TOKEN_SPLIT_RE.split(files_raw) if f]
+        slices[sid] = {
+            "deps_raw": deps_raw,
+            "files": files,
+            "inferred_files": inferred_by_slice.get(sid, []),
+        }
+        order.append(sid)
+
+    if not slices:
+        _die("no slices found (expected '### Slice <id>: ...' headings)")
+
+    for sid in order:
+        deps_raw = slices[sid]["deps_raw"]
+        if deps_raw == "__MISSING__":
+            _die(
+                f"slice {sid!r} is missing its Depends-on declaration — "
+                "add 'Depends-on: none' if it has no prerequisites."
+            )
+        raw = deps_raw.strip()
+        if raw.lower() == "none" or raw == "":
+            slices[sid]["deps"] = []
+        else:
+            slices[sid]["deps"] = [d for d in _TOKEN_SPLIT_RE.split(raw) if d]
+
+    for sid in order:
+        for dep in slices[sid]["deps"]:
+            if dep not in slices:
+                _die(f"slice {sid!r} depends on unknown slice {dep!r}.")
+
+    remaining = {sid: set(slices[sid]["deps"]) for sid in order}
+    waves: list[list[str]] = []
+    placed: set = set()
+    while remaining:
+        ready = sorted(s for s, d in remaining.items() if d <= placed)
+        if not ready:
+            _die("dependency cycle among slices: " + ", ".join(sorted(remaining)) + ".")
+        waves.append(ready)
+        for s in ready:
+            placed.add(s)
+            del remaining[s]
+
+    wave_of = {s: i for i, wave in enumerate(waves, 1) for s in wave}
+
+    # Conservative same-wave collision detection (#865): compare the union of
+    # each slice's declared + inferred files, not declared alone, so a step
+    # that plans to touch a file its slice never declared still trips a
+    # collision against another slice's overlapping write.
+    combined_files = {
+        sid: set(slices[sid]["files"]) | set(slices[sid]["inferred_files"])
+        for sid in order
+    }
+
+    collisions: list[dict] = []
+    for i, wave in enumerate(waves, 1):
+        for a in range(len(wave)):
+            for b in range(a + 1, len(wave)):
+                shared = sorted(combined_files[wave[a]] & combined_files[wave[b]])
+                for f in shared:
+                    collisions.append(
+                        {"wave": i, "slices": [wave[a], wave[b]], "file": f}
+                    )
+
+    # Declared-vs-inferred scope mismatches (#865 AC3) — only for slices that
+    # declare slice-level Files; a slice with no declaration has nothing to
+    # reconcile against.
+    scope_mismatches: list[dict] = []
+    for sid in order:
+        declared = slices[sid]["files"]
+        if not declared:
+            continue
+        entry = _scope_mismatch(sid, declared, slices[sid]["inferred_files"])
+        if entry is not None:
+            scope_mismatches.append(entry)
+
+    return {
+        "schema": "plan-waves/v1",
+        "waves": waves,
+        "slices": {
+            sid: {
+                "depends_on": slices[sid]["deps"],
+                "files": slices[sid]["files"],
+                "wave": wave_of[sid],
+            }
+            for sid in order
+        },
+        "collisions": collisions,
+        "scope_mismatches": scope_mismatches,
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="plan_waves.py",
+        description="Compute parallel build waves from a plan's slice DAG.",
+    )
+    parser.add_argument("plan", nargs="?", help="Path to the plan markdown file")
+    args = parser.parse_args(argv)
+    if not args.plan:
+        sys.stderr.write("usage: plan-waves.sh <plan.md>\n")
+        return 2
+    plan_path = Path(args.plan)
+    if not plan_path.is_file():
+        sys.stderr.write("usage: plan-waves.sh <plan.md>\n")
+        return 2
+    payload = compute_waves(plan_path)
+    print(json.dumps(payload, indent=2, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

package/scripts/pr_close_keyword_lint.py

@@ -0,0 +1,108 @@
+#!/usr/bin/env python3
+"""pr_close_keyword_lint.py — flag accidental issue auto-close phrasing (#977).
+
+GitHub's closing-keyword parser pattern-matches
+`(close|closes|closed|fix|fixes|fixed|resolve|resolves|resolved)\\s+#\\d+`
+literally, anywhere in a merged PR/commit body — it does not understand
+negation. "This does not close #123" still auto-closes #123 on merge.
+
+This script scans a drafted PR body and flags two accidental-match shapes,
+never blocking:
+
+1. A closing keyword immediately preceding an issue number, with a negation
+   word (not, never, won't, doesn't, ...) earlier in the same sentence —
+   the exact shape that caused #977.
+2. A closing keyword match for an issue number that the body also lists
+   under a non-closing `Part of #N` reference — a self-contradictory body.
+
+Usage:
+  python3 pr_close_keyword_lint.py --body-file <path> [--json]
+  echo "$BODY" | python3 pr_close_keyword_lint.py [--json]
+
+Always exits 0 (advisory only). Stdlib-only.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from dataclasses import asdict, dataclass
+
+CLOSE_RE = re.compile(
+    r"\b(close[sd]?|fix(?:e[sd])?|resolve[sd]?)\s+#(\d+)", re.IGNORECASE
+)
+PART_OF_RE = re.compile(r"\bpart of\s+#(\d+)", re.IGNORECASE)
+NEGATION_RE = re.compile(
+    r"\b(not|never|no longer|won't|wont|don't|dont|doesn't|doesnt|"
+    r"isn't|isnt|cannot|can't|cant)\b",
+    re.IGNORECASE,
+)
+SENTENCE_BOUNDARY_RE = re.compile(r"[.\n]")
+
+
+@dataclass
+class Finding:
+    issue: int
+    type: str
+    context: str
+
+
+def _sentence_start(body: str, match_start: int) -> int:
+    """Return the index just after the nearest sentence boundary before
+    match_start, or 0 if none (start of body)."""
+    boundary = -1
+    for m in SENTENCE_BOUNDARY_RE.finditer(body, 0, match_start):
+        boundary = m.end()
+    return max(boundary, 0)
+
+
+def find_findings(body: str) -> list[Finding]:
+    part_of_issues = {int(n) for n in PART_OF_RE.findall(body)}
+    findings: list[Finding] = []
+
+    for match in CLOSE_RE.finditer(body):
+        issue = int(match.group(2))
+        clause_start = _sentence_start(body, match.start())
+        clause = body[clause_start : match.start()]
+        context = body[clause_start : match.end()].strip()
+
+        if NEGATION_RE.search(clause):
+            findings.append(
+                Finding(issue=issue, type="negated-closing-keyword", context=context)
+            )
+        elif issue in part_of_issues:
+            findings.append(
+                Finding(issue=issue, type="conflicts-with-part-of", context=context)
+            )
+
+    return findings
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--body-file", help="Path to the drafted PR body")
+    parser.add_argument("--json", action="store_true", help="Emit findings as JSON")
+    args = parser.parse_args(argv[1:])
+
+    if args.body_file:
+        with open(args.body_file, "r", encoding="utf-8") as handle:
+            body = handle.read()
+    else:
+        body = sys.stdin.read()
+
+    findings = find_findings(body)
+
+    if args.json:
+        print(json.dumps({"findings": [asdict(f) for f in findings]}))
+    elif findings:
+        for finding in findings:
+            print(
+                f'warning: issue #{finding.issue} ({finding.type}): "{finding.context}"'
+            )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv))