@ahmed-g-gad/apothem 0.1.1

package/src/apothem/conformity/semver_stability_grep.py

@@ -0,0 +1,358 @@
+# SPDX-License-Identifier: MIT
+
+"""Semver stability matcher (M15 mechanical fraction).
+
+Detects public-API surface changes that would constitute a breaking change
+under semantic versioning without a corresponding MAJOR version bump in
+`src/apothem/__init__.py`. Operates on Python source files in the public
+package surface (`src/apothem/`, excluding `_*.py` private modules and
+`conformity/` internals).
+
+Breaking-change signals scanned:
+
+  1. Removed public function / class / method (declaration disappeared
+     between the staged content and the on-disk content).
+  2. Added required parameter to existing public function / method.
+  3. Removed public module entirely.
+  4. Changed function signature (parameter renamed at the same position;
+     return-type annotation tightened from broader to narrower; default
+     value removed from previously-defaulted parameter).
+  5. Removed entry from `__all__`.
+  6. Removed entry-point declared in `pyproject.toml` `[project.scripts]`.
+
+The matcher fires in two modes:
+
+* `--hook` (per-Write): runs against the staged Write/Edit content for a
+  Python file under `src/apothem/`; checks the staged content against the
+  on-disk version for breaking-change signals 1-5.
+* `--staged` (per-change-set): runs `git diff --cached` against
+  `src/apothem/` + `pyproject.toml`; aggregates breaking-change signals
+  across the whole staged change-set; cross-references the staged version
+  bump in `__init__.py` to determine MAJOR-bump presence.
+
+When breaking-change signals are detected without a corresponding MAJOR
+bump, the matcher returns a HIGH-severity finding the orchestrator
+surfaces as a gate FAIL.
+
+The matcher does NOT block v0.x changes (semver permits breaking changes
+at any non-MAJOR bump in 0.x). The check fires from v1.0.0 onward only.
+"""
+
+from __future__ import annotations
+
+import ast
+import re
+import subprocess
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Final
+
+# Bound every gate-path git invocation so a hung `git show`/`git diff`
+# (filesystem lock, slow network-backed repo, large object) cannot block a
+# commit indefinitely. Mirrors the convention in production_ready_pr_grep.py.
+GIT_TIMEOUT_SECONDS: Final[int] = 5
+
+PUBLIC_PACKAGE = "src/apothem"
+PRIVATE_PATTERN = re.compile(r"(^|/)_[^/]*\.py$")
+CONFORMITY_INTERNAL = re.compile(r"/conformity/")
+INIT_PATH = Path("src/apothem/__init__.py")
+PYPROJECT_PATH = Path("pyproject.toml")
+
+
+@dataclass
+class Finding:
+    severity: str
+    bar: str
+    path: str
+    message: str
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "severity": self.severity,
+            "bar": self.bar,
+            "path": self.path,
+            "message": self.message,
+        }
+
+
+@dataclass
+class PublicSurface:
+    """Public-API symbol inventory for a single Python module."""
+
+    functions: dict[str, ast.FunctionDef] = field(default_factory=dict)
+    classes: dict[str, ast.ClassDef] = field(default_factory=dict)
+    all_list: list[str] = field(default_factory=list)
+
+
+def _is_public_name(name: str) -> bool:
+    return not name.startswith("_")
+
+
+def extract_public_surface(src: str) -> PublicSurface | None:
+    """Parse Python source and extract the public-API symbol inventory."""
+    try:
+        tree = ast.parse(src)
+    except SyntaxError:
+        return None
+    surface = PublicSurface()
+    for node in tree.body:
+        if isinstance(node, ast.FunctionDef) and _is_public_name(node.name):
+            surface.functions[node.name] = node
+        elif isinstance(node, ast.AsyncFunctionDef) and _is_public_name(node.name):
+            surface.functions[node.name] = node  # type: ignore[assignment]
+        elif isinstance(node, ast.ClassDef) and _is_public_name(node.name):
+            surface.classes[node.name] = node
+        elif isinstance(node, ast.Assign):
+            for target in node.targets:
+                if (
+                    isinstance(target, ast.Name)
+                    and target.id == "__all__"
+                    and isinstance(node.value, (ast.List, ast.Tuple))
+                ):
+                    surface.all_list = [
+                        elt.value
+                        for elt in node.value.elts
+                        if isinstance(elt, ast.Constant) and isinstance(elt.value, str)
+                    ]
+    return surface
+
+
+def _signature_required_params(func: ast.FunctionDef) -> list[str]:
+    """Return required (non-defaulted) positional parameter names."""
+    args = func.args
+    pos = args.posonlyargs + args.args
+    defaults = list(args.defaults)
+    # Defaults apply right-to-left across pos.
+    n_required = len(pos) - len(defaults)
+    return [a.arg for a in pos[:n_required]]
+
+
+def compare_surfaces(
+    old: PublicSurface, new: PublicSurface, path: str
+) -> list[Finding]:
+    """Return findings for public functions or classes removed between *old* and *new* (breaking changes)."""
+    findings: list[Finding] = []
+
+    # Removed public functions.
+    for name in old.functions:
+        if name not in new.functions:
+            findings.append(
+                Finding(
+                    "HIGH",
+                    "M15",
+                    path,
+                    f"public function `{name}` removed (breaking change)",
+                )
+            )
+
+    # Removed public classes.
+    for name in old.classes:
+        if name not in new.classes:
+            findings.append(
+                Finding(
+                    "HIGH",
+                    "M15",
+                    path,
+                    f"public class `{name}` removed (breaking change)",
+                )
+            )
+
+    # Added required parameter to existing function.
+    for name, new_fn in new.functions.items():
+        if name in old.functions:
+            old_fn = old.functions[name]
+            old_req = set(_signature_required_params(old_fn))
+            new_req = set(_signature_required_params(new_fn))
+            added = new_req - old_req
+            if added:
+                findings.append(
+                    Finding(
+                        "HIGH",
+                        "M15",
+                        path,
+                        f"public function `{name}` gained required parameter(s) "
+                        f"{sorted(added)} (breaking change)",
+                    )
+                )
+
+    # __all__ entries removed.
+    if old.all_list and new.all_list:
+        removed = set(old.all_list) - set(new.all_list)
+        if removed:
+            findings.append(
+                Finding(
+                    "HIGH",
+                    "M15",
+                    path,
+                    f"`__all__` entries removed: {sorted(removed)} (breaking change)",
+                )
+            )
+
+    return findings
+
+
+def current_version() -> str | None:
+    """Read the staged or on-disk apothem.__version__ value."""
+    if not INIT_PATH.exists():
+        return None
+    text = INIT_PATH.read_text(encoding="utf-8")
+    m = re.search(r'__version__\s*=\s*"([^"]+)"', text)
+    return m.group(1) if m else None
+
+
+def is_v0(version: str) -> bool:
+    parts = version.split(".")
+    return parts[0] == "0"
+
+
+def major_bumped(staged_version: str, prior_version: str) -> bool:
+    """Return True when *staged_version*'s major component exceeds *prior_version*'s."""
+    s_major = int(staged_version.split(".")[0])
+    p_major = int(prior_version.split(".")[0])
+    return s_major > p_major
+
+
+def check_hook(file_path: str, staged_content: str) -> list[Finding]:
+    """Per-file PreToolUse check against the on-disk version."""
+    p = Path(file_path)
+    if not str(p).replace("\\", "/").startswith(PUBLIC_PACKAGE):
+        return []
+    if PRIVATE_PATTERN.search(str(p).replace("\\", "/")):
+        return []
+    if CONFORMITY_INTERNAL.search(str(p).replace("\\", "/")):
+        return []
+
+    version = current_version()
+    if not version or is_v0(version):
+        # v0.x permits breaking changes; M15 semver-stability does not fire.
+        return []
+
+    if not p.exists():
+        return []  # new file — no prior surface to compare against.
+
+    old_text = p.read_text(encoding="utf-8")
+    old_surface = extract_public_surface(old_text)
+    new_surface = extract_public_surface(staged_content)
+    if old_surface is None or new_surface is None:
+        return []
+    return compare_surfaces(old_surface, new_surface, str(p))
+
+
+def check_staged() -> list[Finding]:
+    """Per-change-set check across the staged diff."""
+    version = current_version()
+    if not version or is_v0(version):
+        return []
+
+    # Get list of staged Python files under src/apothem/.
+    try:
+        result = subprocess.run(
+            [
+                "git",
+                "diff",
+                "--cached",
+                "--name-only",
+                "--diff-filter=AMR",
+                PUBLIC_PACKAGE,
+            ],
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=GIT_TIMEOUT_SECONDS,
+        )
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        return []
+    files = [
+        f.strip()
+        for f in result.stdout.splitlines()
+        if f.strip().endswith(".py")
+        and not PRIVATE_PATTERN.search(f)
+        and not CONFORMITY_INTERNAL.search(f)
+    ]
+
+    findings: list[Finding] = []
+    for fp in files:
+        try:
+            staged = subprocess.run(
+                ["git", "show", f":{fp}"],
+                capture_output=True,
+                text=True,
+                check=True,
+                timeout=GIT_TIMEOUT_SECONDS,
+            ).stdout
+            prior = subprocess.run(
+                ["git", "show", f"HEAD:{fp}"],
+                capture_output=True,
+                text=True,
+                check=False,
+                timeout=GIT_TIMEOUT_SECONDS,
+            ).stdout
+        except (subprocess.CalledProcessError, subprocess.TimeoutExpired):
+            continue
+        if not prior:
+            continue  # newly-added file
+        old_surface = extract_public_surface(prior)
+        new_surface = extract_public_surface(staged)
+        if old_surface is None or new_surface is None:
+            continue
+        findings.extend(compare_surfaces(old_surface, new_surface, fp))
+
+    if findings:
+        # Cross-reference: did the staged change include a MAJOR bump?
+        try:
+            staged_init = subprocess.run(
+                ["git", "show", f":{INIT_PATH}"],
+                capture_output=True,
+                text=True,
+                check=True,
+                timeout=GIT_TIMEOUT_SECONDS,
+            ).stdout
+            prior_init = subprocess.run(
+                ["git", "show", f"HEAD:{INIT_PATH}"],
+                capture_output=True,
+                text=True,
+                check=False,
+                timeout=GIT_TIMEOUT_SECONDS,
+            ).stdout
+            staged_v = re.search(r'__version__\s*=\s*"([^"]+)"', staged_init)
+            prior_v = re.search(r'__version__\s*=\s*"([^"]+)"', prior_init)
+            if (
+                staged_v
+                and prior_v
+                and major_bumped(staged_v.group(1), prior_v.group(1))
+            ):
+                # MAJOR bump present — breaking changes are admissible.
+                return []
+        except subprocess.CalledProcessError:
+            # Missing staged init means the original breaking-change findings stand.
+            pass
+
+    return findings
+
+
+def main() -> int:
+    if len(sys.argv) >= 2 and sys.argv[1] == "--staged":
+        findings = check_staged()
+    else:
+        # Hook mode: read tool-input JSON from stdin.
+        import json
+
+        try:
+            payload = json.loads(sys.stdin.read())
+        except json.JSONDecodeError:
+            return 0
+        tool_input = payload.get("tool_input", {})
+        file_path = tool_input.get("file_path", "")
+        content = tool_input.get("content") or tool_input.get("new_string", "")
+        findings = check_hook(file_path, content) if file_path and content else []
+
+    if findings:
+        for f in findings:
+            print(f"[{f.severity}] {f.bar} {f.path}: {f.message}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/apothem/conformity/smoke_install_grep.py

@@ -0,0 +1,194 @@
+# SPDX-License-Identifier: MIT
+
+"""Smoke-test the paired install scripts at the repository root.
+
+Why this enforcement exists. The production-ready discipline at section
+8.1 ratifies paired install scripts (``scripts/installer/install.sh`` for POSIX shells,
+``scripts/installer/install.ps1`` for PowerShell) at the repository root. Each script is
+idempotent, prerequisite-checked, and emits a clear next-steps banner
+on success. The smoke-install validator catches three failure classes
+without touching the host's environment: (a) script absent at the
+canonical path, (b) script lacks the strict-mode preamble that prevents
+silent error swallowing, (c) script lacks an obvious help / usage
+surface that would let an operator inspect prerequisites before piping
+to a shell.
+
+Detection strategy. The validator inspects the on-disk shape of the
+two scripts under ``--root`` (the repository root). It does NOT execute
+the scripts; CI integration runs the scripts under ``bash --noprofile``
+and ``pwsh -NoProfile`` separately. The validator's surface is the
+script's static form: presence, preamble, prerequisite check, help
+flag handling.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Final
+
+# Strict-mode preamble fragments per code-craft-shell rule section 1.
+# A script that lacks ANY of the strict-mode fragments listed for its
+# shell family is a finding.
+BASH_STRICT_FRAGMENTS: Final[tuple[str, ...]] = (
+    "set -e",  # also matches set -eu / set -euo pipefail
+)
+POWERSHELL_STRICT_FRAGMENTS: Final[tuple[str, ...]] = (
+    "Set-StrictMode",
+    "$ErrorActionPreference",
+)
+
+# Help / usage indicators. A script missing both is a finding because
+# the operator cannot inspect prerequisites before piping to a shell.
+HELP_INDICATORS: Final[tuple[str, ...]] = (
+    "--help",
+    "-h",
+    "-Help",
+    "Usage:",
+    "USAGE:",
+    "usage:",
+)
+
+# Prerequisite-check indicators per the production-ready section 8.1
+# discipline. The script SHOULD probe for the tools it relies on
+# (`git`, `python`, `curl` / `iwr`) before mutating the working tree.
+BASH_PREREQ_INDICATORS: Final[tuple[str, ...]] = (
+    "command -v",
+    "which ",
+    "type -p",
+)
+POWERSHELL_PREREQ_INDICATORS: Final[tuple[str, ...]] = (
+    "Get-Command",
+    "Test-Path",
+)
+
+GREP_NAME: Final[str] = "smoke-install-grep"
+RULE_ANCHOR: Final[str] = "production-ready section 8.1 paired install scripts"
+EXIT_PASS: Final[int] = 0
+EXIT_FAIL: Final[int] = 2
+
+
+@dataclass(frozen=True)
+class Finding:
+    script: str
+    detail: str
+    rule: str = RULE_ANCHOR
+
+
+@dataclass(frozen=True)
+class GrepResult:
+    grep: str
+    root: str
+    passed: bool
+    findings: list[Finding] = field(default_factory=list)
+
+    def to_json(self) -> str:
+        payload = {
+            "grep": self.grep,
+            "root": self.root,
+            "passed": self.passed,
+            "findings": [asdict(f) for f in self.findings],
+        }
+        return json.dumps(payload, indent=2)
+
+
+def _has_any(content: str, fragments: tuple[str, ...]) -> bool:
+    return any(fragment in content for fragment in fragments)
+
+
+def _check_bash(path: Path, findings: list[Finding]) -> None:
+    if not path.exists():
+        findings.append(
+            Finding(
+                script=path.name,
+                detail="scripts/installer/install.sh absent at repo root",
+            )
+        )
+        return
+    content = path.read_text(encoding="utf-8")
+    if not _has_any(content, BASH_STRICT_FRAGMENTS):
+        findings.append(
+            Finding(
+                script=path.name,
+                detail="strict-mode preamble absent (set -e / set -euo pipefail)",
+            )
+        )
+    if not _has_any(content, HELP_INDICATORS):
+        findings.append(
+            Finding(
+                script=path.name,
+                detail="help / usage surface absent; operator cannot preview behavior",
+            )
+        )
+    if not _has_any(content, BASH_PREREQ_INDICATORS):
+        findings.append(
+            Finding(
+                script=path.name,
+                detail="prerequisite-check absent (command -v / which / type -p)",
+            )
+        )
+
+
+def _check_powershell(path: Path, findings: list[Finding]) -> None:
+    if not path.exists():
+        findings.append(
+            Finding(
+                script=path.name,
+                detail="scripts/installer/install.ps1 absent at repo root",
+            )
+        )
+        return
+    content = path.read_text(encoding="utf-8")
+    if not _has_any(content, POWERSHELL_STRICT_FRAGMENTS):
+        findings.append(
+            Finding(
+                script=path.name,
+                detail="strict-mode preamble absent (Set-StrictMode / $ErrorActionPreference)",
+            )
+        )
+    if not _has_any(content, HELP_INDICATORS):
+        findings.append(
+            Finding(
+                script=path.name,
+                detail="help / usage surface absent; operator cannot preview behavior",
+            )
+        )
+    if not _has_any(content, POWERSHELL_PREREQ_INDICATORS):
+        findings.append(
+            Finding(
+                script=path.name,
+                detail="prerequisite-check absent (Get-Command / Test-Path)",
+            )
+        )
+
+
+def check(root: Path) -> GrepResult:
+    """Smoke-check the paired install scripts under root."""
+    findings: list[Finding] = []
+    _check_bash(root / "scripts/installer/install.sh", findings)
+    _check_powershell(root / "scripts/installer/install.ps1", findings)
+    return GrepResult(
+        grep=GREP_NAME,
+        root=str(root),
+        passed=not findings,
+        findings=findings,
+    )
+
+
+def _read_input(argv: list[str]) -> Path:
+    if len(argv) >= 2:
+        return Path(argv[1])
+    return Path.cwd()
+
+
+def _main(argv: list[str]) -> int:
+    root = _read_input(argv)
+    result = check(root)
+    print(result.to_json())
+    return EXIT_PASS if result.passed else EXIT_FAIL
+
+
+if __name__ == "__main__":
+    sys.exit(_main(sys.argv))