pi-dev-team 0.2.0

package/scripts/git_origin_host.py

@@ -0,0 +1,88 @@
+#!/usr/bin/env python3
+"""Python port of scripts/git-origin-host.sh (#613 / #572 Phase 3).
+
+Classify the `origin` remote so /plan only offers GitHub issue creation on an
+actual GitHub host.
+
+Prints exactly one of:
+    github  — github.com OR an enterprise GHE host (any dot-label equals "github")
+    other   — a non-GitHub host, including lookalikes like notgithub.example.com
+    none    — no origin remote, or an unparseable URL (fail-open: never blocks)
+
+Reads `git remote get-url origin` unless a URL is given as argv[1] (for testing).
+
+Usage: git_origin_host.py [remote-url]
+
+Stdlib-only. See docs/python-hook-contract.md.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+
+
+def classify(url: str) -> str:
+    """Return "github", "other", or "none" for a remote URL string.
+
+    Extracts the host from https://, ssh://, or scp-like (git@host:path) forms,
+    lowercases it, then matches a whole dot-label of "github" (covers github.com
+    and enterprise GHE such as github.example.com). A substring like "notgithub"
+    or "mygithub" does NOT match, because the pattern requires a dot immediately
+    before "github".
+    """
+    if not url:
+        return "none"
+
+    host = ""
+    if "://" in url:
+        rest = url.split("://", 1)[1]
+        # Strip optional user@ prefix.
+        if "@" in rest:
+            rest = rest.split("@", 1)[1]
+        # Take up to the first `/`, then trim port suffix `:PORT`.
+        host = rest.split("/", 1)[0]
+        host = host.split(":", 1)[0]
+    elif "@" in url and ":" in url.split("@", 1)[1]:
+        # scp-like: user@host:path
+        rest = url.split("@", 1)[1]
+        host = rest.split(":", 1)[0]
+    else:
+        host = url.split(":", 1)[0]
+
+    host = host.lower()
+    if not host:
+        return "none"
+
+    # Match a whole dot-label of "github".
+    if ".github." in "." + host + ".":
+        return "github"
+    return "other"
+
+
+def read_origin_url() -> str:
+    """Return `git remote get-url origin` stdout, or "" on any failure."""
+    try:
+        completed = subprocess.run(
+            ["git", "remote", "get-url", "origin"],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except (FileNotFoundError, OSError):
+        return ""
+    if completed.returncode != 0:
+        return ""
+    return completed.stdout.strip()
+
+
+def main(argv: list) -> int:
+    url = argv[1] if len(argv) > 1 else ""
+    if not url:
+        url = read_origin_url()
+    print(classify(url))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv))

package/scripts/install-java-static-analysis.py

@@ -0,0 +1,110 @@
+#!/usr/bin/env python3
+"""install-java-static-analysis.py — install a pinned PMD distribution.
+
+Stdlib-only (urllib.request, zipfile) so it runs unchanged on macOS, Linux,
+and Windows — no curl, unzip, or Git Bash required (ADR 0014).
+"""
+import hashlib
+import hmac
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import urllib.request
+import zipfile
+from pathlib import Path
+
+PMD_VERSION = "7.7.0"  # single source of truth for the pin; bump deliberately
+                       # (check https://github.com/pmd/pmd/releases)
+# SHA-256 of pmd-dist-7.7.0-bin.zip, pinned alongside the version above so the
+# two can never drift apart — verified against the published GitHub release
+# asset (curl the release URL below, then `shasum -a 256`). Bump together
+# with PMD_VERSION.
+PMD_SHA256 = "be8bf68f6c1d66984bd9645a93e631b78a1c2f42f5f0f8719082fead67553940"
+if len(PMD_SHA256) != 64 or any(c not in "0123456789abcdef" for c in PMD_SHA256):
+    # Fail loudly at import time, not at the end of a real download — a
+    # malformed pin (wrong length, uppercase, stray whitespace) must never
+    # silently degrade into "every install fails checksum" discovered only
+    # in the field.
+    raise ValueError(f"PMD_SHA256 is not a 64-char lowercase hex digest: {PMD_SHA256!r}")
+
+
+def main() -> int:
+    if shutil.which("java") is None:
+        print("java (JDK/JRE) is required but not found.", file=sys.stderr)
+        return 1
+    # Repo-local by default (run from the repo root): per-repo version
+    # reproducibility, no cross-repo version skew. Gitignored, never committed.
+    install_dir = Path(
+        os.environ.get("PMD_INSTALL_DIR", str(Path.cwd() / ".pmd"))
+    )
+    local_launcher = (
+        install_dir / f"pmd-bin-{PMD_VERSION}" / "bin"
+        / ("pmd.bat" if os.name == "nt" else "pmd")
+    )
+    if local_launcher.exists():
+        print(f"pmd already installed: {local_launcher}")
+        return 0
+    if shutil.which("pmd") is not None:  # PATH fallback (env-override installs)
+        version = subprocess.run(
+            ["pmd", "--version"], capture_output=True, text=True, check=False
+        ).stdout.strip()
+        print(f"pmd already installed on PATH: {version}")
+        return 0
+
+    install_dir.mkdir(parents=True, exist_ok=True)
+    archive = f"pmd-dist-{PMD_VERSION}-bin.zip"
+    # %2F is a deliberately percent-encoded slash: the real PMD release tag is
+    # literally "pmd_releases/{PMD_VERSION}" (a slash inside one path
+    # segment), not two path segments — do not "fix" this to a literal "/".
+    # This exact fragment is also asserted, separately, by
+    # scripts/verify_pmd_checksum_pin.py's _check_url_shape_matches_installer.
+    url = (
+        "https://github.com/pmd/pmd/releases/download/"
+        f"pmd_releases%2F{PMD_VERSION}/{archive}"
+    )
+
+    print(f"Downloading PMD {PMD_VERSION}...")
+    with tempfile.TemporaryDirectory() as tmp:
+        zip_path = Path(tmp) / archive
+        urllib.request.urlretrieve(url, zip_path)
+
+        digest = hashlib.sha256()
+        with zip_path.open("rb") as fh:
+            for chunk in iter(lambda: fh.read(65536), b""):
+                digest.update(chunk)
+        if not hmac.compare_digest(digest.hexdigest(), PMD_SHA256.strip().lower()):
+            print(
+                f"Downloaded archive checksum mismatch: expected {PMD_SHA256}, "
+                f"got {digest.hexdigest()}. Refusing to extract.",
+                file=sys.stderr,
+            )
+            return 1
+
+        with zipfile.ZipFile(zip_path) as zf:
+            zf.extractall(install_dir)
+
+    bin_dir = install_dir / f"pmd-bin-{PMD_VERSION}" / "bin"
+    # zipfile does not preserve the executable bit; restore it on the two
+    # launchers only (no-op on Windows) rather than every extracted entry.
+    for name in ("pmd", "pmd.bat"):
+        launcher = bin_dir / name
+        if launcher.exists():
+            launcher.chmod(launcher.stat().st_mode | 0o755)
+
+    print(f"PMD installed to {bin_dir}")
+    print("No PATH change needed: detection probes the repo-local .pmd/ bin "
+          "first, then falls back to PATH (per #811).")
+    if "PMD_INSTALL_DIR" not in os.environ:
+        gitignore = Path(".gitignore")
+        if not (gitignore.exists() and ".pmd/" in gitignore.read_text()):
+            print("Reminder: add `.pmd/` to this repo's .gitignore — the PMD "
+                  "distribution is large and must never be committed.")
+    launcher = bin_dir / ("pmd.bat" if os.name == "nt" else "pmd")
+    subprocess.run([str(launcher), "--version"], check=True)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/issue_deps.py

@@ -0,0 +1,74 @@
+#!/usr/bin/env python3
+"""Python port of scripts/issue-deps.sh (#614 / #572 Phase 3).
+
+Per-slice sibling dependency sets for issue linking, derived from the plan's
+DAG (via plan_waves.py), NOT from plan file order. Read-only: never edits the
+plan or plan-waves output.
+
+Emits JSON mapping each slice id to its DIRECT predecessor slice ids:
+
+    { "A": [], "B": ["A"], "C": ["A"], "D": ["B","C"] }
+
+/issues-from-plan maps those slice ids to the child issue numbers it creates
+and renders "depends on #N" links between siblings.
+
+Usage: issue_deps.py <plan.md>
+
+Delegates DAG analysis to plan_waves.py — same reason as build_wave.py: until
+plan_waves.py converts, calling into it preserves the single source of truth
+for cycle / missing / unknown-dep diagnostics.
+
+Stdlib-only. See docs/python-hook-contract.md.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+
+def _here() -> Path:
+    return Path(__file__).resolve().parent
+
+
+def _run_plan_waves(plan_file: str):
+    plan_waves = _here() / "plan_waves.py"
+    return subprocess.run(
+        [sys.executable, str(plan_waves), plan_file],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+
+
+def main(argv: list) -> int:
+    if len(argv) < 2 or not argv[1] or not os.path.isfile(argv[1]):
+        print("usage: issue-deps.sh <plan.md>", file=sys.stderr)
+        return 2
+
+    result = _run_plan_waves(argv[1])
+    if result.returncode != 0:
+        # Propagate plan-waves' error + exit code verbatim.
+        sys.stderr.write(result.stderr)
+        return result.returncode
+
+    try:
+        waves_json = json.loads(result.stdout)
+    except json.JSONDecodeError as exc:
+        print(f"issue-deps: plan_waves.py emitted invalid JSON: {exc}", file=sys.stderr)
+        return 1
+
+    # `.slices | map_values(.depends_on)` in jq → { <sid>: [<dep>, …] }.
+    slices = waves_json.get("slices") or {}
+    out = {sid: (spec.get("depends_on") or []) for sid, spec in slices.items()}
+
+    # jq's default pretty-print: 2-space indent, LF terminator.
+    print(json.dumps(out, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv))

package/scripts/lib/_bdd_markers.py

@@ -0,0 +1,28 @@
+"""_bdd_markers — the shared per-language BDD pending-marker table.
+
+Hoisted out of `gherkin_stub_gate.py` (issue #1421 bug 5): that module's
+`_MARKERS_BY_EXT` used to be imported by `stub_extractors/__init__.py` via a
+`sys.path` reach-up into the parent `scripts/` entry-point layer and a
+leading-underscore "private" name — the only module under `scripts/lib/` in
+the whole repo that imported from its own parent layer (every sibling lib
+module, `_vendored_tree.py`/`_gherkin_text.py` included, is either
+stdlib-only or imports lib siblings). This module is the shared home both
+`gherkin_stub_gate.py` and `stub_extractors/__init__.py` import from instead,
+under a public name.
+
+Extension (lowercase) -> (language label, pending marker substrings).
+
+Stdlib-only. (ADR 0014/0015).
+"""
+
+from __future__ import annotations
+
+MARKERS_BY_EXT = {
+    ".js": ("JS/TS", ("this.pending()",)),
+    ".ts": ("JS/TS", ("this.pending()",)),
+    ".mjs": ("JS/TS", ("this.pending()",)),
+    ".cjs": ("JS/TS", ("this.pending()",)),
+    ".java": ("Java", ("PendingException",)),
+    ".cs": ("C#", ("PendingStepException", "StepIsPending()")),
+    ".go": ("Go", ("godog.ErrPending",)),
+}

package/scripts/lib/_gherkin_text.py

@@ -0,0 +1,93 @@
+"""_gherkin_text.py — line-level Gherkin text primitives shared across the
+`.feature`-file *parsers* (`gherkin_feature_merge.py`, `gherkin_failure_path_gate.py`,
+`gherkin_cross_feature_duplicate_titles_gate.py`), plus a general
+untrusted-text/path terminal-safety helper also used by `gherkin_stub_gate.py`
+(a step-definition scanner — it never parses `.feature` files, and imports only
+`safe_for_terminal`, none of the Gherkin block-parsing primitives below).
+
+Hoisted out after `_stripped()` and the `Feature:`/`Scenario:`/`Scenario
+Outline:` prefix constants were found duplicated byte-for-byte between the two
+`.feature`-file parsers (issue #1420 code-review follow-up) — the same "third
+occurrence" threshold `_vendored_tree.py` was extracted at. `is_tag_line`/
+`safe_for_terminal` and `trim_trailing_tag_run` joined later (issue #1526) at
+that same third-occurrence point — the latter closes the trailing `@tag`/
+blank-line look-back loop that was independently duplicated in all three
+`.feature`-file parsers (`gherkin_feature_merge.py`'s `_block_end`, and the two
+gate scripts' own block-scanning loops).
+
+Stdlib-only. (ADR 0014/0015).
+"""
+
+from __future__ import annotations
+
+import re
+
+FEATURE_PREFIX = "Feature:"
+SCENARIO_OUTLINE_PREFIX = "Scenario Outline:"
+SCENARIO_PREFIX = "Scenario:"
+
+# Full C0 + C1 control-character range, plus Unicode line/paragraph
+# separators and bidirectional-control characters — stripped before printing
+# untrusted scanned-file content (or a path derived from it) to a terminal.
+# A `.feature` file's content (titles, and the path it was found at) comes
+# from whatever repository is being scanned, and could otherwise:
+#   - inject terminal escape sequences (CWE-150) via the C0/C1 range;
+#   - forge a fake extra report line via an embedded CR/LF (C0), or via
+#     U+2028/U+2029, which several terminals still render as a hard line
+#     break even though they're outside the ASCII control range;
+#   - visually spoof a printed path/title (Trojan-Source-style) via a
+#     bidirectional-override character (U+202A-U+202E) or isolate
+#     (U+2066-U+2069), reordering how the surrounding text renders.
+# Titles are always single lines (parsed via `splitlines()` then `.strip()`),
+# so stripping any of these from title text is a no-op; a filesystem path
+# has no such guarantee, so the full range is needed now that this function
+# also sanitizes paths. `repr()`-based print sites (e.g.
+# `gherkin_feature_merge.py`'s check-stale branch) don't need this guard —
+# Python's `repr()` already escapes every character struck here.
+CONTROL_CHARS = re.compile("[\x00-\x1f\x7f-\x9f\u2028\u2029\u202a-\u202e\u2066-\u2069]")
+
+TERMINAL_DISPLAY_LIMIT = 200
+
+
+def stripped(line: str) -> str:
+    """Strip only the line ending, preserving all other whitespace — so a
+    caller reconstructing text from `splitlines(keepends=True)` output stays
+    byte-exact for everything except the ending itself."""
+    return line.rstrip("\r\n")
+
+
+def safe_for_terminal(text: str, limit: int = TERMINAL_DISPLAY_LIMIT) -> str:
+    """Strip control characters and bound length before printing untrusted
+    scanned-file text (or a path derived from it) to a terminal — the
+    `--json` path is unaffected, `json.dumps` already escapes control
+    characters. Apply this to every piece of untrusted text reaching a
+    terminal print, including file paths: a filename is drawn from the same
+    untrusted repository as titles and can legally contain control bytes on
+    POSIX filesystems."""
+    return CONTROL_CHARS.sub("", text)[:limit]
+
+
+def is_tag_line(line: str) -> bool:
+    """True when `line` is a Gherkin `@tag` line (every token starts with
+    `@`) — used to walk a Feature block's trailing tag/blank-line run back
+    onto the *next* block it actually belongs to, not this one."""
+    text = stripped(line).strip()
+    if not text:
+        return False
+    return all(tok.startswith("@") for tok in text.split())
+
+
+def trim_trailing_tag_run(lines: list, header_index: int, end_index: int) -> int:
+    """Back `end_index` up past a trailing `@tag`/blank-line run so it lands
+    on the true end of the Feature block starting at `header_index` —
+    Gherkin tags attach to the declaration that *follows* them, so a
+    `@tag` (or blank line) immediately preceding the next Feature: header
+    belongs to that next block, not this one. Without this, a tag on the
+    following Feature block would leak into this block's body."""
+    while end_index > header_index + 1:
+        prev = lines[end_index - 1]
+        if stripped(prev).strip() == "" or is_tag_line(prev):
+            end_index -= 1
+        else:
+            break
+    return end_index

package/scripts/lib/_vendored_tree.py

@@ -0,0 +1,70 @@
+"""scripts/lib/_vendored_tree.py — shared vendored/generated-directory
+pruning helper.
+
+Extracted (issue #1420) from `detect_bdd_convention.py` and
+`gherkin_stub_gate.py`, which each carried a byte-for-byte-identical copy of
+this logic. A third caller (`gherkin_failure_path_gate.py`) made the
+duplication the third occurrence — the threshold where it becomes a shared
+helper rather than a per-script judgment call. Lives under `scripts/lib/`,
+per this repo's established shared-helper convention (see `plan_parse.py`
+and its callers) — each of the three callers above resolves this directory
+onto `sys.path` via `sys.path.insert(0, str(Path(__file__).resolve().parent
+/ "lib"))` before importing it.
+
+Stdlib-only. (ADR 0014/0015).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from pathlib import Path
+
+# Trees whose contents are a dependency's (or a build's), never the project's
+# own convention/surface.
+VENDORED_DIR_NAMES = frozenset({".git", "node_modules", "vendor", "dist", "build"})
+
+# Presence of this file marks a directory as a virtualenv, whatever its name.
+_VIRTUALENV_MARKER = "pyvenv.cfg"
+
+
+def is_vendored_dir(directory: Path) -> bool:
+    """True for vendored/generated trees a scan must never walk into or
+    treat as project signal."""
+    if directory.name in VENDORED_DIR_NAMES:
+        return True
+    return (directory / _VIRTUALENV_MARKER).is_file()
+
+
+def iter_files(root: Path) -> Iterator[Path]:
+    """Yield files under `root`, pruning vendored trees and symlinks. This
+    skips a symlinked *file* as well as a symlinked directory — a scan must
+    never grep the same underlying file twice under two different paths,
+    and never loop forever chasing a symlink cycle a directory-only check
+    wouldn't catch."""
+    pending = [root]
+    while pending:
+        directory = pending.pop()
+        for entry in sorted(directory.iterdir()):
+            if entry.is_symlink():
+                continue
+            if entry.is_dir() and not is_vendored_dir(entry):
+                pending.append(entry)
+            elif entry.is_file():
+                yield entry
+
+
+def find_files(directories: list, predicate) -> list:
+    """Return every file under `directories` for which `predicate(path)` is
+    true, pruning vendored trees via `iter_files`, sorted for deterministic
+    output. Shared by `gherkin_failure_path_gate.py` and
+    `gherkin_stub_gate.py`, whose directory-scan-and-filter functions were
+    structurally identical apart from the filter predicate (differing only
+    in which file extensions they cared about)."""
+    found = []
+    for directory in directories:
+        if not directory.is_dir():
+            continue
+        for path in iter_files(directory):
+            if predicate(path):
+                found.append(path)
+    return sorted(set(found))