codeplain 0.3.11.dev12__tar.gz → 0.3.11.dev14__tar.gz

{codeplain-0.3.11.dev12 → codeplain-0.3.11.dev14}/.flake8

@@ -20,6 +20,8 @@ exclude =
 per-file-ignores =
     __init__.py: F401
     tests/*: U100
+# require_git() runs between imports in plain_modules.py, so the imports below it trip E402
+    plain_modules.py: E402
 max-complexity = 15
 enable-extensions = U100
 # Plugin-specific configuration

{codeplain-0.3.11.dev12 → codeplain-0.3.11.dev14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: codeplain
-Version: 0.3.11.dev12
+Version: 0.3.11.dev14
 Summary: Transform plain language specifications into working code
 License-File: LICENSE
 Classifier: Environment :: Console

codeplain-0.3.11.dev14/git_preflight.py

@@ -0,0 +1,41 @@
+"""Verify a working git is available before GitPython is imported.
+
+GitPython probes for the git executable on import and raises from module scope
+if it is missing or broken, so the CLI would crash with a traceback before
+main() could explain it.
+"""
+
+import shutil
+import subprocess
+import sys
+
+from plain2code_console import console
+
+GIT_MISSING_MESSAGE = "git is not installed. Please install git and try again."
+GIT_BROKEN_MESSAGE = "git is installed but not working. Please repair your git installation and try again."
+MACOS_BROKEN_GIT_HINT = (
+    "This usually means the Command Line Tools are missing; install them with 'xcode-select --install'."
+)
+
+
+def git_runs(git_path):
+    """Whether `git version` succeeds. A git on PATH can still be unusable: on
+    macOS without the Command Line Tools /usr/bin/git is a stub that exits with
+    an xcrun error, and GIT_PYTHON_REFRESH=quiet does not suppress that."""
+    try:
+        return subprocess.run([git_path, "version"], capture_output=True, timeout=10).returncode == 0
+    except (OSError, subprocess.SubprocessError):
+        return False
+
+
+def require_git():
+    """Exit with a clean message unless a working git is available."""
+    git_path = shutil.which("git")
+    if git_path is None:
+        console.error(f"{GIT_MISSING_MESSAGE}\n")
+        sys.exit(1)
+
+    if not git_runs(git_path):
+        hint = f"\n{MACOS_BROKEN_GIT_HINT}" if sys.platform == "darwin" else ""
+        console.error(f"{GIT_BROKEN_MESSAGE}{hint}\n")
+        sys.exit(1)

{codeplain-0.3.11.dev12 → codeplain-0.3.11.dev14}/plain_file.py

@@ -615,15 +615,45 @@ def parse_plain_source(  # noqa: C901
                 f"Plain syntax error: Syntax error at line {nested_acceptance_test_heading.line_number}: {plain_spec.ACCEPTANCE_TEST_HEADING} heading should be nested under specific functional spec."
             )
 
+    defined_concepts = set[str]()
     if plain_source[plain_spec.DEFINITIONS] is not None:
         with PlainRenderer() as renderer:
             for token in plain_source[plain_spec.DEFINITIONS].children:
                 rendered_token = renderer.render(token)
                 new_concepts, _ = concept_utils.extract_concepts_from_definition(rendered_token)
+                defined_concepts.update(new_concepts)
                 for concept in new_concepts:
                     if concept in required_concepts:
                         required_concepts.remove(concept)
 
+    if EXPORTED_CONCEPTS_DIRECTIVE in plain_source_obj.metadata:
+        module_name = modules_trace[-1] if modules_trace else None
+        subject = f"Module '{module_name}'" if module_name else "Module"
+
+        for entry in plain_source_obj.metadata[EXPORTED_CONCEPTS_DIRECTIVE]:
+            exported_concepts, errors = concept_utils.extract_concepts_from_definition(entry)
+            if errors:
+                raise PlainSyntaxError(
+                    f"Plain syntax error: {subject} exports an invalid concept (`{entry}`). "
+                    f"Expected a concept token, e.g. :ConceptName:."
+                )
+
+            for exported_concept in exported_concepts:
+                if exported_concept in concept_utils.DEFAULT_CONCEPTS:
+                    raise PlainSyntaxError(
+                        f"Plain syntax error: {subject} cannot export default concept {exported_concept}. "
+                        f"Only user-defined concepts can be exported."
+                    )
+
+                if exported_concept not in defined_concepts:
+                    message = f"Plain syntax error: {subject} exports undefined concept {exported_concept}."
+                    if REQUIRES_DIRECTIVE in plain_source_obj.metadata:
+                        message += (
+                            " An exported concept must be defined in this module's definitions or in an "
+                            "imported module; a concept inherited through requires cannot be re-exported."
+                        )
+                    raise PlainSyntaxError(message)
+
     required_modules = []
     if REQUIRES_DIRECTIVE in plain_source_obj.metadata:
         required_modules = plain_source_obj.metadata[REQUIRES_DIRECTIVE]
@@ -710,15 +740,7 @@ def process_required_modules(
         if EXPORTED_CONCEPTS_DIRECTIVE in plain_file_parse_result.plain_source_obj.metadata:
             exported_concepts = list[str]()
             for concept in plain_file_parse_result.plain_source_obj.metadata[EXPORTED_CONCEPTS_DIRECTIVE]:
-                if concept in concept_utils.DEFAULT_CONCEPTS:
-                    raise PlainSyntaxError(
-                        f"Plain syntax error: Default concept cannot be exported: {concept}. Only user-defined concepts can be exported."
-                    )
-
-                if isinstance(concept, str):
-                    exported_concepts.extend(concept_utils.extract_concepts_from_definition(concept)[0])
-                else:
-                    raise PlainSyntaxError(f"Plain syntax error: Invalid exported concept: {concept}.")
+                exported_concepts.extend(concept_utils.extract_concepts_from_definition(concept)[0])
 
             with PlainRenderer() as renderer:
                 for exported_concept in exported_concepts:

{codeplain-0.3.11.dev12 → codeplain-0.3.11.dev14}/plain_modules.py

@@ -6,18 +6,18 @@ import tempfile
 import zipfile
 from functools import cached_property
 
+from git_preflight import require_git
 from plain2code_exceptions import (
-    GitNotInstalledError,
     InvalidModuleArchiveError,
     MissingPreviousFunctionalitiesError,
     ModuleDoesNotExistError,
 )
 
-try:
-    from git import Repo
-    from git.exc import NoSuchPathError
-except ImportError:
-    raise GitNotInstalledError("git is not installed. Please install git and try again.")
+# Must run before GitPython is imported, which raises on a missing or broken git.
+require_git()
+
+from git import Repo
+from git.exc import NoSuchPathError
 
 import file_utils
 import git_utils

codeplain-0.3.11.dev14/tests/data/plainfileparser/cyclic_definitions.plain

@@ -0,0 +1,9 @@
+***definitions***
+- :A: relates to :B:.
+- :B: relates to :A:.
+
+***implementation reqs***
+- The :A: concept must be implemented.
+
+***functional specs***
+- Implement a wrapper for the :A: concept.

codeplain-0.3.11.dev14/tests/data/plainfileparser/exported_concepts_defaults_exported.plain

@@ -0,0 +1,13 @@
+---
+exported_concepts:
+    - :UnitTests:
+---
+
+***definitions***
+- :NewConcept: is a new concept.
+
+***implementation reqs***
+- The :NewConcept: must be implemented.
+
+***functional specs***
+- Implement a wrapper for the :NewConcept: concept.

codeplain-0.3.11.dev14/tests/data/plainfileparser/exported_concepts_imported_exported.plain

@@ -0,0 +1,12 @@
+---
+import:
+    - exported_concepts_base
+exported_concepts:
+    - :Concept:
+---
+
+***implementation reqs***
+- The :Concept: concept must be implemented.
+
+***functional specs***
+- Implement a wrapper for the :Concept: concept.

codeplain-0.3.11.dev14/tests/data/plainfileparser/exported_concepts_inherited_reexported.plain

@@ -0,0 +1,15 @@
+---
+requires:
+    - exported_concepts
+exported_concepts:
+    - :Concept:
+---
+
+***definitions***
+- :DependantConcept: depends on the :Concept: concept.
+
+***implementation reqs***
+- The :DependantConcept: concept must be implemented.
+
+***functional specs***
+- Implement a wrapper for the :DependantConcept: concept.

codeplain-0.3.11.dev14/tests/data/plainfileparser/exported_concepts_malformed.plain

@@ -0,0 +1,13 @@
+---
+exported_concepts:
+    - not a concept at all
+---
+
+***definitions***
+- :A: is a concept.
+
+***implementation reqs***
+- The :A: concept must be implemented.
+
+***functional specs***
+- Implement a wrapper for the :A: concept.

codeplain-0.3.11.dev14/tests/data/plainfileparser/exported_concepts_missing_definition.plain

@@ -0,0 +1,14 @@
+---
+exported_concepts:
+    - :NewConcept:
+    - :Concept:
+---
+
+***definitions***
+- :NewConcept: is a new concept.
+
+***implementation reqs***
+- The :NewConcept: must be implemented.
+
+***functional specs***
+- Implement a wrapper for the :NewConcept: concept.

codeplain-0.3.11.dev14/tests/data/plainfileparser/exported_concepts_missing_definition_example.plain

@@ -0,0 +1,13 @@
+---
+requires:
+    - exported_concepts_missing_definition
+---
+
+***definitions***
+- :AnotherConcept: is a new concept.
+
+***implementation reqs***
+- :AnotherConcept: must be implemented.
+
+***functional specs***
+- Implement a wrapper for the :AnotherConcept: concept.

codeplain-0.3.11.dev14/tests/data/plainfileparser/exported_concepts_multiple_per_bullet.plain

@@ -0,0 +1,14 @@
+---
+exported_concepts:
+    - :NewConcept:, :OtherConcept:
+---
+
+***definitions***
+- :NewConcept: is a new concept.
+- :OtherConcept: is another concept.
+
+***implementation reqs***
+- The :NewConcept: and :OtherConcept: concepts must be implemented.
+
+***functional specs***
+- Implement a wrapper for the :NewConcept: and :OtherConcept: concepts.

codeplain-0.3.11.dev14/tests/data/plainfileparser/exported_concepts_multiple_per_bullet_undefined.plain

@@ -0,0 +1,13 @@
+---
+exported_concepts:
+    - :NewConcept:, :OtherConcept:
+---
+
+***definitions***
+- :NewConcept: is a new concept.
+
+***implementation reqs***
+- The :NewConcept: concept must be implemented.
+
+***functional specs***
+- Implement a wrapper for the :NewConcept: concept.

codeplain-0.3.11.dev14/tests/data/plainfileparser/exported_concepts_no_definitions.plain

@@ -0,0 +1,10 @@
+---
+exported_concepts:
+    - :Concept:
+---
+
+***implementation reqs***
+- :Implementation: is a simple wrapper.
+
+***functional specs***
+- :Implementation: has an entry point.

codeplain-0.3.11.dev12/tests/data/plainfileparser/exported_concepts_missing_example.plain → codeplain-0.3.11.dev14/tests/data/plainfileparser/exported_concepts_not_declared_example.plain

@@ -1,6 +1,6 @@
 ---
 requires:
-    - exported_concepts_missing
+    - exported_concepts_not_declared
 ---
 
 ***definitions***

codeplain-0.3.11.dev14/tests/test_git_preflight.py

@@ -0,0 +1,98 @@
+"""Regression tests for issue #133.
+
+When git is unusable the CLI must report a clean message and exit 1, never dump
+a traceback. The failure is at import time (GitPython raises from module scope
+before main() runs), so the CLI is run in a subprocess and asserted on what a
+user would actually see. sys.executable is launched by absolute path, so
+replacing PATH only controls which git, if any, can be found.
+"""
+
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+from git_preflight import GIT_BROKEN_MESSAGE, GIT_MISSING_MESSAGE
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+TRACEBACK_MARKER = "Traceback (most recent call last)"
+
+# The crash was in the import chain, so it hit every entry point equally.
+CLI_INVOCATIONS = [["--version"], ["--status"], ["does-not-exist.plain"]]
+
+
+def run_cli(args, path_dir=None):
+    """Run the CLI and return its exit code and output, stripped of styling and
+    with whitespace collapsed, so assertions survive console line wrapping."""
+    env = os.environ.copy()
+    # Drop GitPython overrides so the PATH search decides whether git is found.
+    env.pop("GIT_PYTHON_GIT_EXECUTABLE", None)
+    env.pop("GIT_PYTHON_REFRESH", None)
+    env.setdefault("CODEPLAIN_API_KEY", "dummy")
+    if path_dir is not None:
+        env["PATH"] = str(path_dir)
+
+    result = subprocess.run(
+        [sys.executable, "plain2code.py", *args],
+        cwd=REPO_ROOT,
+        env=env,
+        capture_output=True,
+        text=True,
+        timeout=120,
+    )
+    output = re.sub(r"\x1b\[[0-9;]*m", "", result.stdout + result.stderr)
+    return result.returncode, " ".join(output.split())
+
+
+@pytest.fixture
+def no_git_dir(tmp_path):
+    """A directory containing no git at all, used as the whole PATH."""
+    d = tmp_path / "no-git"
+    d.mkdir()
+    return d
+
+
+@pytest.fixture
+def broken_git_dir(tmp_path):
+    """A directory whose git resolves but always fails, used as the whole PATH.
+    This is the shape of macOS without the Command Line Tools."""
+    d = tmp_path / "broken-git"
+    d.mkdir()
+    if sys.platform == "win32":
+        (d / "git.bat").write_text("@echo off\nexit /b 127\n")
+    else:
+        git = d / "git"
+        git.write_text("#!/bin/sh\nexit 127\n")
+        git.chmod(0o755)
+    return d
+
+
+@pytest.mark.parametrize("args", CLI_INVOCATIONS)
+def test_missing_git_reports_cleanly(args, no_git_dir):
+    rc, output = run_cli(args, no_git_dir)
+
+    assert GIT_MISSING_MESSAGE in output, output
+    assert TRACEBACK_MARKER not in output, output
+    # GitPython's own advice about GIT_PYTHON_REFRESH must not reach the user.
+    assert "GIT_PYTHON_REFRESH" not in output, output
+    assert rc == 1, output
+
+
+@pytest.mark.parametrize("args", CLI_INVOCATIONS)
+def test_broken_git_reports_cleanly(args, broken_git_dir):
+    rc, output = run_cli(args, broken_git_dir)
+
+    assert GIT_BROKEN_MESSAGE in output, output
+    assert GIT_MISSING_MESSAGE not in output, output
+    assert TRACEBACK_MARKER not in output, output
+    assert rc == 1, output
+
+
+def test_cli_works_when_git_is_present():
+    rc, output = run_cli(["--version"])
+
+    assert rc == 0, output
+    assert "codeplain version" in output, output

{codeplain-0.3.11.dev12 → codeplain-0.3.11.dev14}/tests/test_plainfileparser.py

@@ -632,6 +632,11 @@ def test_concept_validation_acceptance_tests(get_test_data_path):
         )
 
 
+def test_concept_validation_cyclic_definitions(get_test_data_path):
+    with pytest.raises(PlainSyntaxError, match="cycles in the concept graph"):
+        plain_file.plain_file_parser("cyclic_definitions.plain", [get_test_data_path("data/plainfileparser")])
+
+
 def test_required_concepts(get_test_data_path):
     plain_file.plain_file_parser(
         "required_concepts_example.plain",
@@ -661,28 +666,36 @@ def test_required_concepts(get_test_data_path):
         )
 
 
-def test_exported_concepts(get_test_data_path):
-    plain_file.plain_file_parser(
+@pytest.mark.parametrize(
+    "fixture",
+    [
         "exported_concepts_example.plain",
-        [get_test_data_path("data/plainfileparser")],
-    )
-
-    plain_file.plain_file_parser(
+        "exported_concepts_imported_exported.plain",
+        "exported_concepts_multiple_per_bullet.plain",
         "exported_concepts_nested_example.plain",
-        [get_test_data_path("data/plainfileparser")],
-    )
-
-    with pytest.raises(PlainSyntaxError):
-        plain_file.plain_file_parser(
-            "exported_concepts_missing_example.plain",
-            [get_test_data_path("data/plainfileparser")],
-        )
-
-    with pytest.raises(PlainSyntaxError):
-        plain_file.plain_file_parser(
-            "exported_concepts_transitive_example.plain",
-            [get_test_data_path("data/plainfileparser")],
-        )
+    ],
+)
+def test_exported_concepts_valid(get_test_data_path, fixture):
+    plain_file.plain_file_parser(fixture, [get_test_data_path("data/plainfileparser")])
+
+
+@pytest.mark.parametrize(
+    ("fixture", "expected_word"),
+    [
+        ("exported_concepts_defaults_exported.plain", "cannot export default concept"),
+        ("exported_concepts_inherited_reexported.plain", "cannot be re-exported"),
+        ("exported_concepts_malformed.plain", "exports an invalid concept"),
+        ("exported_concepts_missing_definition_example.plain", "'exported_concepts_missing_definition' exports"),
+        ("exported_concepts_missing_definition.plain", "exports undefined concept"),
+        ("exported_concepts_multiple_per_bullet_undefined.plain", "exports undefined concept"),
+        ("exported_concepts_no_definitions.plain", "exports undefined concept"),
+        ("exported_concepts_not_declared_example.plain", "not defined"),
+        ("exported_concepts_transitive_example.plain", "not defined"),
+    ],
+)
+def test_exported_concepts_invalid(get_test_data_path, fixture, expected_word):
+    with pytest.raises(PlainSyntaxError, match=expected_word):
+        plain_file.plain_file_parser(fixture, [get_test_data_path("data/plainfileparser")])
 
 
 def test_topological_sort(get_test_data_path):