patchground 0.1.0__py3-none-any.whl

patchground/verify/vitest_adapter.py

@@ -0,0 +1,252 @@
+"""Bounded, non-executing TypeScript syntax analysis for the canonical Vitest runner."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from types import MappingProxyType
+
+import tree_sitter_typescript
+from tree_sitter import Language, Node, Parser
+
+MAX_SOURCE_BYTES = 1024 * 1024
+_MAX_NODES = 200_000
+_MAX_DEPTH = 256
+_LANGUAGE = Language(tree_sitter_typescript.language_typescript())
+_FORBIDDEN = frozenset(
+    {
+        "describe",
+        "suite",
+        "it",
+        "beforeAll",
+        "afterAll",
+        "beforeEach",
+        "afterEach",
+    }
+)
+
+
+class UnsupportedVitest(Exception):
+    """Unsupported or ambiguous syntax; diagnostics never contain authored source."""
+
+
+@dataclass(frozen=True)
+class TestDefinition:
+    name: str
+    fingerprint: str
+    start: int
+    end: int
+    callee_end: int
+    assertions: int
+
+
+@dataclass(frozen=True)
+class TestModule:
+    definitions: Mapping[str, TestDefinition]
+    helper_fingerprint: str
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "definitions", MappingProxyType(dict(self.definitions)))
+
+
+def is_test_filename(name: str) -> bool:
+    return name.endswith(".test.ts")
+
+
+def _walk(root: Node) -> list[Node]:
+    result: list[Node] = []
+    stack = [(root, 0)]
+    while stack:
+        node, depth = stack.pop()
+        if depth > _MAX_DEPTH or len(result) >= _MAX_NODES:
+            raise UnsupportedVitest("Module syntax exceeds analysis bounds")
+        result.append(node)
+        stack.extend((child, depth + 1) for child in reversed(node.children))
+    return result
+
+
+def _literal(node: Node) -> str:
+    raw = node.text
+    if node.type != "string" or raw is None:
+        raise UnsupportedVitest("Test names must be literal strings")
+    # Deliberately reject JS escape syntax rather than approximate its decoding.
+    if b"\\" in raw:
+        raise UnsupportedVitest("Escaped literals are unsupported")
+    try:
+        value = raw[1:-1].decode("utf-8")
+    except UnicodeError as exc:
+        raise UnsupportedVitest("Invalid source encoding") from exc
+    return value
+
+
+def _fingerprint(nodes: list[Node]) -> str:
+    digest = hashlib.sha256()
+    for root in nodes:
+        for node in _walk(root):
+            if node.type in {"comment", ";"}:
+                continue
+            # Token text plus node kinds preserves syntax without whitespace or comments.
+            if not node.children:
+                digest.update(
+                    json.dumps(
+                        [node.type, (node.text or b"").decode("utf-8")], ensure_ascii=True
+                    ).encode()
+                )
+            else:
+                digest.update(node.type.encode() + b"\0")
+    return digest.hexdigest()
+
+
+def _read(path: Path) -> bytes:
+    with path.open("rb") as stream:
+        source = stream.read(MAX_SOURCE_BYTES + 1)
+    if len(source) > MAX_SOURCE_BYTES:
+        raise UnsupportedVitest("Module exceeds 1 MiB")
+    try:
+        source.decode("utf-8")
+    except UnicodeError as exc:
+        raise UnsupportedVitest("Invalid source encoding") from exc
+    return source
+
+
+def parse_module(path: Path) -> TestModule:
+    source = _read(path)
+    root = Parser(_LANGUAGE).parse(source).root_node
+    nodes = _walk(root)
+    if root.has_error:
+        raise UnsupportedVitest("Invalid TypeScript syntax")
+    allowed: set[int] = set()
+    imported: set[str] = set()
+    for statement in root.named_children:
+        if statement.type != "import_statement":
+            continue
+        module = statement.child_by_field_name("source")
+        if module is None or _literal(module) != "vitest":
+            continue
+        if any(n.type == "type" for n in _walk(statement)):
+            raise UnsupportedVitest("Type-only Vitest imports are unsupported")
+        specifiers = [n for n in _walk(statement) if n.type == "import_specifier"]
+        if not specifiers:
+            raise UnsupportedVitest("Canonical named Vitest imports required")
+        for specifier in specifiers:
+            name = specifier.child_by_field_name("name")
+            if (
+                name is None
+                or specifier.child_by_field_name("alias") is not None
+                or name.text not in {b"test", b"expect"}
+                or any(n.type == "type" for n in specifier.children)
+            ):
+                raise UnsupportedVitest("Unsupported Vitest import")
+            value = (name.text or b"").decode()
+            if value in imported:
+                raise UnsupportedVitest("Duplicate Vitest import")
+            imported.add(value)
+            allowed.add(name.id)
+        if any(
+            n.type in {"namespace_import", "identifier"} and n.id not in allowed
+            for n in _walk(statement)
+        ):
+            raise UnsupportedVitest("Unsupported Vitest import")
+    definitions: dict[str, TestDefinition] = {}
+    statements: set[int] = set()
+    for statement in root.named_children:
+        if statement.type != "expression_statement" or len(statement.named_children) != 1:
+            continue
+        call = statement.named_children[0]
+        callee = call.child_by_field_name("function")
+        if call.type != "call_expression" or callee is None or callee.text != b"test":
+            continue
+        if any(n.type in {"type_arguments", "optional_chain", "?."} for n in call.children):
+            raise UnsupportedVitest("Unsupported test call syntax")
+        arguments = call.child_by_field_name("arguments")
+        args = (
+            []
+            if arguments is None
+            else [n for n in arguments.named_children if n.type != "comment"]
+        )
+        if (
+            "test" not in imported
+            or len(args) != 2
+            or args[1].type not in {"arrow_function", "function_expression"}
+        ):
+            raise UnsupportedVitest("Unsupported test registration")
+        test_name = _literal(args[0])
+        if (
+            not test_name
+            or len(test_name) > 200
+            or not test_name.isprintable()
+            or test_name.strip() != test_name
+        ):
+            raise UnsupportedVitest("Test identity is not safely representable")
+        if test_name in definitions:
+            raise UnsupportedVitest("Duplicate test identity")
+        allowed.add(callee.id)
+        statements.add(statement.id)
+        callback = args[1]
+        assertions = 0
+        for node in _walk(callback):
+            if node.type != "call_expression":
+                continue
+            fn = node.child_by_field_name("function")
+            if fn is None or fn.type != "member_expression":
+                continue
+            obj = fn.child_by_field_name("object")
+            while obj is not None and obj.type == "member_expression":
+                prop = obj.child_by_field_name("property")
+                if prop is None or prop.text not in {b"not", b"resolves", b"rejects"}:
+                    break
+                obj = obj.child_by_field_name("object")
+            if obj is not None and obj.type == "call_expression":
+                expect = obj.child_by_field_name("function")
+                if expect is not None and expect.type == "identifier" and expect.text == b"expect":
+                    if any(n.type in {"optional_chain", "?."} for n in _walk(node)):
+                        raise UnsupportedVitest("Optional assertion calls are unsupported")
+                    allowed.add(expect.id)
+                    assertions += 1
+        definitions[test_name] = TestDefinition(
+            test_name,
+            _fingerprint([statement]),
+            statement.start_byte,
+            statement.end_byte,
+            callee.end_byte,
+            assertions,
+        )
+    for node in nodes:
+        if node.type not in {
+            "identifier",
+            "shorthand_property_identifier",
+            "shorthand_property_identifier_pattern",
+            "property_identifier",
+        }:
+            continue
+        if b"\\" in (node.text or b""):
+            raise UnsupportedVitest("Escaped identifiers are unsupported")
+        text = (node.text or b"").decode("utf-8")
+        if text in _FORBIDDEN or (text in {"test", "expect"} and node.id not in allowed):
+            raise UnsupportedVitest("Registration symbols are shadowed, leaked or unsupported")
+    if "expect" not in imported and any(d.assertions for d in definitions.values()):
+        raise UnsupportedVitest("Canonical expect import required")
+    helpers = [n for n in root.named_children if n.id not in statements and n.type != "comment"]
+    return TestModule(definitions, _fingerprint(helpers))
+
+
+def skip_module(path: Path) -> None:
+    module = parse_module(path)
+    source = _read(path)
+    for definition in sorted(module.definitions.values(), key=lambda d: d.callee_end, reverse=True):
+        source = source[: definition.callee_end] + b".skip" + source[definition.callee_end :]
+    path.write_bytes(source)
+
+
+def select_tests(path: Path, names: set[str]) -> None:
+    module = parse_module(path)
+    if not names <= module.definitions.keys():
+        raise UnsupportedVitest("Selected test identity is missing")
+    source = _read(path)
+    for definition in sorted(module.definitions.values(), key=lambda d: d.start, reverse=True):
+        if definition.name not in names:
+            source = source[: definition.start] + source[definition.end :]
+    path.write_bytes(source)

patchground-0.1.0.dist-info/METADATA

@@ -0,0 +1,258 @@
+Metadata-Version: 2.5
+Name: patchground
+Version: 0.1.0
+Summary: Local-first CLI for practicing real software engineering on broken repositories.
+Project-URL: Homepage, https://patchground.dev
+Project-URL: Documentation, https://github.com/franndeli/patchground#readme
+Project-URL: Repository, https://github.com/franndeli/patchground
+Project-URL: Issues, https://github.com/franndeli/patchground/issues
+Project-URL: Changelog, https://github.com/franndeli/patchground/blob/main/CHANGELOG.md
+Author: Fran Delicado
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: challenges,cli,debugging,docker,practice,software-engineering
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Education
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.12
+Requires-Dist: defusedxml>=0.7.1
+Requires-Dist: docker>=7.1
+Requires-Dist: junitparser>=4.0
+Requires-Dist: pydantic>=2.10
+Requires-Dist: requests>=2.32
+Requires-Dist: rich>=13.9
+Requires-Dist: ruamel-yaml>=0.18.10
+Requires-Dist: tree-sitter-typescript==0.23.2
+Requires-Dist: tree-sitter==0.26.0
+Requires-Dist: typer>=0.15
+Requires-Dist: urllib3>=2.0
+Provides-Extra: ai
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/franndeli/patchground/main/web/public/favicon.svg" width="72" height="72" alt="">
+</p>
+
+<h1 align="center">Patchground</h1>
+
+<p align="center"><em>Real code. Real problems. Your tools.</em></p>
+
+<p align="center">
+  <a href="https://github.com/franndeli/patchground/actions/workflows/ci.yml"><img src="https://github.com/franndeli/patchground/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a>
+  <a href="https://github.com/franndeli/patchground/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="License: Apache-2.0"></a>
+  <img src="https://img.shields.io/badge/python-3.12%2B-blue" alt="Python 3.12+">
+  <a href="https://patchground.dev"><img src="https://img.shields.io/badge/website-patchground.dev-0a7" alt="Website"></a>
+</p>
+
+Patchground is an open-source, local-first CLI (`patchground`, short alias `pgnd`) for practising
+real software engineering. You get a small but realistic repository with a bug to find or a feature
+to finish. You solve it in your own editor, with your own AI or none. Patchground runs the checks,
+including hidden ones, in Docker and reports verified outcomes rather than a score.
+
+- **Local-first.** No account, no hosted execution, no telemetry. Sessions are plain folders on your
+  machine.
+- **Your tools.** Any editor, any assistant. Patchground never needs an API key.
+- **Verified, not graded.** Checks run in a locked-down container. The final report states facts,
+  such as which tests pass, whether you added a regression test and what you changed. It never gives
+  an overall score.
+
+> **Status: 0.1.0, early release.** Seven curated Python and TypeScript challenges ship with the
+> CLI: debugging, feature work and an architecture refactor. Difficulty is not yet human-rated.
+
+## Quick start
+
+You need Python 3.12+, [uv](https://docs.astral.sh/uv/), Git and a running Docker engine (Docker
+Desktop on macOS, Docker Engine on Linux, WSL2 on Windows).
+
+```sh
+uv tool install git+https://github.com/franndeli/patchground   # or: pipx install git+https://...
+pgnd doctor                       # checks Docker, Git and disk space, and prints exact fixes
+pgnd list --builtin               # the curated challenges bundled with the CLI
+pgnd show pagination-last-page    # read the ticket first
+pgnd start pagination-last-page   # builds the image and creates your session workspace
+```
+
+Open the printed workspace in your editor. From that workspace:
+
+```sh
+pgnd status
+pgnd check
+# Edit the code, then run pgnd check again.
+# To discard edits and try again:
+pgnd reset
+```
+
+Outside a session directory, select it explicitly with `pgnd check --session <session-path>` or
+`pgnd status --session <session-path>`. There is no implicit latest-session fallback. All commands
+support `--json`; `start` also accepts `--no-timer` and `--no-history`. `reset --json` requires `--yes`.
+
+`list --builtin` shows the curated challenges bundled with the CLI; `pgnd start <id>` and
+`pgnd show <id>` accept their IDs. `list [directory]` scans only immediate challenge folders
+(default: the current directory), and `list --installed` shows pinned packs. All of them take
+`--type`, `--lang`, `--difficulty` and `--tag` filters. Invalid candidates are reported even when
+filters are active. Discovery never builds, runs or grants trust. A bare ID resolves to an existing
+local folder first, then a unique installed pack challenge, then a built-in challenge.
+
+Reset restores ordinary starting files and removes ordinary additions, but preserves `.git`,
+credential-pattern entries (`.env*`, `*.pem`, `*.key`, `id_*`), the timer and event history. Stop
+editors/agents from writing while resetting. Unsafe paths or protected-file collisions are rejected;
+filesystem failure can leave a partial reset. Status keeps the last historical check; run a new check
+for the restored workspace. There is no undo or automatic backup.
+
+Doctor probes engine reachability/version, Git, and at least 1 GiB free on the session disk. It does
+not measure the Docker VM disk or guarantee enough space for every image. It never builds or runs a
+challenge. Follow its suggested fixes before starting.
+
+See [the first-session guide](https://github.com/franndeli/patchground/blob/main/docs/first-session.md)
+for the full loop and troubleshooting, and [challenge packs](https://github.com/franndeli/patchground/blob/main/docs/packs.md)
+for installing third-party challenges.
+
+Sessions live under `~/patchground/sessions/`; set `PATCHGROUND_SESSIONS_DIR` to an absolute path
+to keep them elsewhere. Each gets a new Git repository with an initial
+baseline commit. Checks never change its HEAD, branches or staging area. The manifest and hidden
+checks are frozen in private session metadata outside the editable workspace; removing the original
+challenge folder does not break the attempt. The reference solution is never copied.
+
+Image builds can use the network; checks run on an internal Docker network with resource limits.
+Start validates structure and builds—it does not run the reference-validation gate. Use
+`pgnd validate <challenge-path>` when authoring. Only start local challenges you authored or reviewed:
+opening a workspace in your editor can execute project tooling outside Patchground's sandbox.
+
+A check exits `0` only when it has tests and all pass, `1` for nonpassing results (including skipped
+checks), and `2` for invalid input or infrastructure problems. Raw test output is never printed.
+Status works without Docker. A removed session image must be restored or a new session started;
+check does not silently rebuild or pull it. Multi-container services remain deferred; challenges
+must use `environment.services: []`.
+
+## Practice tools
+
+```sh
+pgnd hint
+pgnd run -- python -m pytest tests/test_pagination.py
+pgnd history
+pgnd sessions
+```
+
+Hints come from frozen authored metadata; exhaustion succeeds without another event. `run` executes
+literal arguments in a disposable container copy with no hidden checks and no host environment
+forwarding. Container edits are discarded. It displays only a sanitized output tail (up to 64 KiB),
+not verification evidence, and saves neither arguments nor output in session events. Put Patchground
+options before `--`, for example `pgnd run --json -- python --version`. Use explicit `sh -c` only
+when you want shell syntax inside the container.
+
+New sessions capture initial and completed-check checkpoints in private session Git storage, never
+in your branches or staging area. `start --no-history` opts out; older sessions are not migrated.
+History skips credential patterns and Git-ignored files, and reports unavailable capture separately
+from passing/failing tests. It is filtered history, not a complete replay of ignored files used by
+checks or frozen submission evidence. `history` is read-only and remains available after submission;
+periodic capture and snapshot restoration are not implemented. Reset still restores originals.
+Unsupported or unsafe ignore contexts—including Git includes, linked-worktree metadata, relative
+exclusion paths and unsupported Git environment overrides—make history unavailable rather than
+silently retaining ignored files; checks remain usable.
+
+## Finish an attempt
+
+```sh
+pgnd submit
+pgnd report
+# Outside the workspace:
+pgnd report --session <session-path> --json
+```
+
+Submit captures the checked ordinary files, runs fresh checks and saves an immutable local report.
+It can finalize a failed attempt (exit `1`); missing regression evidence is explicit, not a pass or
+submission gate. Repeating submit returns the same result without rerunning. Further check/reset/hint/run
+operations are rejected; start a new session to practice again. Your workspace remains editable,
+but later edits cannot change the saved report. Report reads need no Docker.
+
+For supported conventional pytest tests, regression evidence selects genuinely new/changed test
+definitions and requires them to fail on original code and pass on final code. Pre-existing failures,
+skips, missing tests, collection problems and unsupported/changed harnesses do not count as proof.
+The report also records changed checked files (including ordinary Git-ignored files), expected-path
+scope, structural test removals, elapsed time and practice-check/hint counts. Binary/non-UTF-8 or
+over-1-MiB line counts are unestablished. Assertion-count reductions are facts, not judgments about
+semantic test strength. There is no overall score or AI judgment.
+
+Infrastructure errors before finalization leave the attempt open. If a failure occurs after the
+bundle is published, retry submit to verify/reconcile it rather than assuming rollback. This is
+local evidence, not tamper-proof attestation. See [the feedback contract](https://github.com/franndeli/patchground/blob/main/docs/contracts/feedback.md).
+
+## Author a challenge
+
+```sh
+pgnd new my-challenge
+pgnd validate my-challenge
+```
+
+`new` defaults to `--type debug --lang python` and creates a runnable teaching starter in the
+current directory. It refuses any existing destination and never builds or runs automatically.
+Only that template combination is currently supported. The starter includes an intentional defect,
+checks and a reference patch; replace them together rather than changing only the ticket.
+See [the authoring guide](https://github.com/franndeli/patchground/blob/main/docs/authoring.md) for the full workflow and safety limits.
+
+The curated challenges live in `examples/` and ship inside the package as the built-in catalog. They
+are Docker-validated, not yet human-rated for difficulty or realism.
+
+## Validate an authored challenge
+
+`pgnd validate <path>` builds once, proves the broken state fails and the reference passes, then
+checks determinism across three runs each of visible-only, combined and reference checks (nine
+check containers for this part). Test IDs, statuses, occurrence counts and outcomes must agree; ordering
+and timing may differ. A mismatch fails at `determinism`. Only structured results are reported.
+
+Success writes a local `verification.json`; failure removes an earlier Patchground record.
+Use `--no-write` for read-only validation. Three stable runs are bounded evidence, not a guarantee
+that a challenge can never be flaky.
+
+For supported Python/pytest layouts, `anti_gaming` then probes an empty diff, deletion of editable
+test modules, and skipping those modules (three more containers, twelve total). Hidden test IDs,
+counts and statuses must match the broken baseline exactly. Mutations use disposable copies and
+never change authored files or hidden checks. Conventional `test_*.py` / `*_test.py` modules with
+static `test_*` functions or methods in `Test*` classes are supported; helper-only modules are kept.
+
+Other runners/layouts, absent editable tests, or ineffective mutations are explicitly `not_run`,
+not passed. A `valid` result means all executed gates passed: inspect step statuses before claiming
+anti-gaming coverage. This bounded probe does not prevent malicious test runners, forged results,
+custom discovery/plugin bypasses or local cheating.
+
+## Website
+
+The product homepage, [patchground.dev](https://patchground.dev), lives in `web/`. Preview it locally with
+`npm --prefix web run dev`, then open `http://127.0.0.1:4173`. It introduces the CLI, local practice
+workflow and real challenges, with contribution as a secondary path. It does not host execution.
+The challenge catalog is generated from `examples/*/challenge.yaml` (`npm --prefix web run catalog`).
+See the web README for checks, the static build, and the separate deployment approval gate.
+
+## Develop
+
+```sh
+git clone https://github.com/franndeli/patchground && cd patchground
+uv sync
+uv run pgnd validate examples/pagination-last-page
+uv run ruff check . && uv run ruff format --check . && uv run mypy
+uv run pytest                 # Docker tests are skipped if no engine is reachable
+PATCHGROUND_REQUIRE_DOCKER=1 uv run pytest -m docker  # require integration tests to run
+```
+
+One-time setup per clone: `brew install gitleaks && git config core.hooksPath .githooks`.
+
+Specs: `goal-and-requirements.md`, `architecture.md`, `docs/contracts/`, `src/patchground/*/SPEC.md`.
+
+## Contributing and security
+
+Bug reports, challenge feedback and pull requests are welcome; see
+[CONTRIBUTING](https://github.com/franndeli/patchground/blob/main/.github/CONTRIBUTING.md).
+Please report vulnerabilities privately, as described in the
+[security policy](https://github.com/franndeli/patchground/blob/main/.github/SECURITY.md).
+
+## License
+
+Apache-2.0 for the CLI. Each challenge declares its own `content_license`.