codeplain 0.2.6__tar.gz → 0.2.8__tar.gz

{codeplain-0.2.6 → codeplain-0.2.8}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: codeplain
-Version: 0.2.6
+Version: 0.2.8
 Summary: Transform plain language specifications into working code
 License-File: LICENSE
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
 Classifier: Operating System :: OS Independent
 Classifier: Topic :: Software Development :: Code Generators
-Requires-Python: >=3.11
+Requires-Python: ~=3.11.0
 Requires-Dist: gitpython==3.1.42
 Requires-Dist: mistletoe==1.3.0
 Requires-Dist: networkx==3.6.1

{codeplain-0.2.6 → codeplain-0.2.8}/config/system_config.yaml

@@ -1,4 +1,4 @@
-client_version: "0.2.6"
+client_version: "0.2.8"
 
 error_messages:
   template_not_found:

codeplain-0.2.8/docs/plain2code_cli.md

@@ -0,0 +1,63 @@
+# Plain2Code CLI Reference
+
+```text
+usage: generate_cli.py [-h] [--verbose] [--base-folder BASE_FOLDER] [--build-folder BUILD_FOLDER] [--log-to-file | --no-log-to-file] [--log-file-name LOG_FILE_NAME] [--config-name CONFIG_NAME] [--render-range RENDER_RANGE | --render-from RENDER_FROM] [--force-render]
+                       [--unittests-script UNITTESTS_SCRIPT] [--conformance-tests-folder CONFORMANCE_TESTS_FOLDER] [--conformance-tests-script CONFORMANCE_TESTS_SCRIPT] [--prepare-environment-script PREPARE_ENVIRONMENT_SCRIPT] [--api [API]] [--api-key API_KEY]
+                       [--full-plain] [--dry-run] [--replay-with REPLAY_WITH] [--template-dir TEMPLATE_DIR] [--copy-build] [--build-dest BUILD_DEST] [--copy-conformance-tests] [--conformance-tests-dest CONFORMANCE_TESTS_DEST] [--render-machine-graph]
+                       [--logging-config-path]
+                       filename
+
+Render plain code to target code.
+
+positional arguments:
+  filename              Path to the plain file to render. The directory containing this file has highest precedence for template loading, so you can place custom templates here to override the defaults. See --template-dir for more details about template loading.
+
+options:
+  -h, --help            show this help message and exit
+  --verbose, -v         Enable verbose output
+  --base-folder BASE_FOLDER
+                        Base folder for the build files
+  --build-folder BUILD_FOLDER
+                        Folder for build files
+  --log-to-file, --no-log-to-file
+                        Enable logging to a file. Defaults to True. Use --no-log-to-file to disable.
+  --log-file-name LOG_FILE_NAME
+                        Name of the log file. Defaults to 'codeplain.log'.Always resolved relative to the plain file directory.If file on this path already exists, it will be overwritten by the current logs.
+  --render-range RENDER_RANGE
+                        Specify a range of functional requirements to render (e.g. '1.1,2.3'). Use comma to separate start and end IDs. If only one ID is provided, only that requirement is rendered. Range is inclusive of both start and end IDs.
+  --render-from RENDER_FROM
+                        Continue generation starting from this specific functional requirement (e.g. '2.1'). The requirement with this ID will be included in the output. The ID must match one of the functional requirements in your plain file.
+  --force-render        Force re-render of all the required modules.
+  --unittests-script UNITTESTS_SCRIPT
+                        Shell script to run unit tests on generated code. Receives the build folder path as its first argument (default: 'plain_modules').
+  --conformance-tests-folder CONFORMANCE_TESTS_FOLDER
+                        Folder for conformance test files
+  --conformance-tests-script CONFORMANCE_TESTS_SCRIPT
+                        Path to conformance tests shell script. The script should accept two arguments: 1) First argument: path to a folder (e.g. 'plain_modules/module_name') containing generated source code, 2) Second argument: path to a subfolder of the conformance
+                        tests folder (e.g. 'conformance_tests/subfoldername') containing test files.
+  --prepare-environment-script PREPARE_ENVIRONMENT_SCRIPT
+                        Path to a shell script that prepares the testing environment. The script should accept the build folder path as its first argument (default: 'plain_modules').
+  --api [API]           Alternative base URL for the API. Default: `https://api.codeplain.ai`
+  --api-key API_KEY     API key used to access the API. If not provided, the CODEPLAIN_API_KEY environment variable is used.
+  --full-plain          Display the complete plain specification before code generation. This shows your plain file with any included template content expanded. Useful for understanding what content is being processed.
+  --dry-run             Preview of what Codeplain would do without actually making any changes.
+  --replay-with REPLAY_WITH
+  --template-dir TEMPLATE_DIR
+                        Path to a custom template directory. Templates are searched in the following order: 1) directory containing the plain file, 2) this custom template directory (if provided), 3) built-in standard_template_library directory
+  --copy-build          If set, copy the build folder to `--build-dest` after every successful rendering.
+  --build-dest BUILD_DEST
+                        Target folder to copy build output to (used only if --copy-build is set).
+  --copy-conformance-tests
+                        If set, copy the conformance tests folder to `--conformance-tests-dest` after every successful rendering. Requires --conformance-tests-script.
+  --conformance-tests-dest CONFORMANCE_TESTS_DEST
+                        Target folder to copy conformance tests output to (used only if --copy-conformance-tests is set).
+  --render-machine-graph
+                        If set, render the state machine graph.
+  --logging-config-path
+                        Path to the logging configuration file.
+
+configuration:
+  --config-name CONFIG_NAME
+                        Path to the config file, defaults to config.yaml
+
+```

{codeplain-0.2.6 → codeplain-0.2.8}/git_utils.py

@@ -1,4 +1,5 @@
 import os
+from configparser import NoOptionError, NoSectionError
 from typing import Optional, Union
 
 from git import Repo
@@ -42,6 +43,24 @@ def _get_full_commit_message(message, module_name, frid, render_id) -> str:
     return full_message
 
 
+def _ensure_git_config(repo: Repo) -> None:
+    config = repo.config_reader()
+
+    try:
+        config.get_value("user", "name")
+    except (NoSectionError, NoOptionError):
+        # user.name not configured, set a default at repo level
+        with repo.config_writer(config_level="repository") as writer:
+            writer.set_value("user", "name", "Codeplain")
+
+    try:
+        config.get_value("user", "email")
+    except (NoSectionError, NoOptionError):
+        # user.email not configured, set a default at repo level
+        with repo.config_writer(config_level="repository") as writer:
+            writer.set_value("user", "email", "codeplain@localhost")
+
+
 def init_git_repo(
     path_to_repo: Union[str, os.PathLike], module_name: Optional[str] = None, render_id: Optional[str] = None
 ) -> Repo:
@@ -56,6 +75,7 @@ def init_git_repo(
         os.makedirs(path_to_repo)
 
     repo = Repo.init(path_to_repo)
+    _ensure_git_config(repo)
     repo.git.commit(
         "--allow-empty", "-m", _get_full_commit_message(INITIAL_COMMIT_MESSAGE, module_name, None, render_id)
     )

{codeplain-0.2.6 → codeplain-0.2.8}/install/walkthrough.sh

@@ -13,13 +13,13 @@ NC="${NC:-\033[0m}"
 # Onboarding Step 1: Introduction to Plain
 clear
 echo ""
-echo -e "${GRAY}────────────────────────────────────────────${NC}"
-echo -e "  ${YELLOW}${BOLD}quick intro to ***plain specification language${NC} - Step 1 of 5"
-echo -e "${GRAY}────────────────────────────────────────────${NC}"
+echo -e "${GRAY}─────────────────────────────────────────────────────────${NC}"
+echo -e "  ${YELLOW}${BOLD}***plain specification language intro${NC} - Step 1 of 5"
+echo -e "${GRAY}─────────────────────────────────────────────────────────${NC}"
 echo ""
-echo -e "  ***plain is a language of spec-driven development that allows developers to express intent on any level of detail."
+echo -e "  ***plain is a language of spec-driven development that allows developers to express intent at any level of detail."
 echo ""
-echo -e "  write specs in ${YELLOW}plain English${NC}, in markdown with additional syntax"
+echo -e "  write specs in natural language extended with additional syntax based on markdown."
 echo ""
 echo -e "  render production-ready code with *codeplain."
 echo ""
@@ -28,8 +28,8 @@ echo ""
 echo -e "${GRAY}  ┌────────────────────────────────────────────────────────┐${NC}"
 echo -e "${GRAY}  │${NC}                                                        ${GRAY}│${NC}"
 echo -e "${GRAY}  │${NC}  ${YELLOW}***definitions***${NC}      - key concepts in your app     ${GRAY}│${NC}"
-echo -e "${GRAY}  │${NC}  ${YELLOW}***implementation reqs***${NC}  - implementation details       ${GRAY}│${NC}"
-echo -e "${GRAY}  │${NC}  ${YELLOW}***test reqs***${NC}       - testing requirements         ${GRAY}│${NC}"
+echo -e "${GRAY}  │${NC}  ${YELLOW}***implementation reqs***${NC}  - implementation details   ${GRAY}│${NC}"
+echo -e "${GRAY}  │${NC}  ${YELLOW}***test reqs***${NC}       - testing requirements          ${GRAY}│${NC}"
 echo -e "${GRAY}  │${NC}  ${YELLOW}***functional specs***${NC} - what the app should do       ${GRAY}│${NC}"
 echo -e "${GRAY}  │${NC}                                                        ${GRAY}│${NC}"
 echo -e "${GRAY}  └────────────────────────────────────────────────────────┘${NC}"
@@ -41,33 +41,32 @@ read -r -p "  press [Enter] to continue..." < /dev/tty
 # Onboarding Step 2: Functional Specification
 clear
 echo ""
-echo -e "${GRAY}────────────────────────────────────────────${NC}"
-echo -e "  ${YELLOW}${BOLD}Plain Language 101${NC} - Step 2 of 5"
-echo -e "${GRAY}────────────────────────────────────────────${NC}"
+echo -e "${GRAY}─────────────────────────────────────────────────────────${NC}"
+echo -e "  ${YELLOW}${BOLD}***plain specification language intro${NC} - Step 2 of 5"
+echo -e "${GRAY}─────────────────────────────────────────────────────────${NC}"
 echo ""
 echo -e "  ${WHITE}${BOLD}FUNCTIONAL SPECS${NC} - what should the app do?"
 echo ""
 echo -e "  This is where you describe ${GREEN}what your app should do${NC},"
-echo -e "  written in plain English. No code, just requirements."
+echo -e "  written in natural language. No code, just requirements."
 echo ""
 echo -e "${GRAY}  ┌────────────────────────────────────────────────────────┐${NC}"
 echo -e "${GRAY}  │${NC}                                                        ${GRAY}│${NC}"
-echo -e "${GRAY}  │${NC}  ${GRAY}***definitions***${NC}                                    ${GRAY}│${NC}"
+echo -e "${GRAY}  │${NC}  ${GRAY}***definitions***${NC}                                     ${GRAY}│${NC}"
 echo -e "${GRAY}  │${NC}                                                        ${GRAY}│${NC}"
-echo -e "${GRAY}  │${NC}  ${GRAY}- :App: is a console application.${NC}                    ${GRAY}│${NC}"
+echo -e "${GRAY}  │${NC}  ${GRAY}- :App: is a console application.${NC}                     ${GRAY}│${NC}"
 echo -e "${GRAY}  │${NC}                                                        ${GRAY}│${NC}"
-echo -e "${GRAY}  │${NC}  ${GRAY}***implementation reqs***${NC}                                ${GRAY}│${NC}"
+echo -e "${GRAY}  │${NC}  ${GRAY}***implementation reqs***${NC}                             ${GRAY}│${NC}"
 echo -e "${GRAY}  │${NC}                                                        ${GRAY}│${NC}"
-echo -e "${GRAY}  │${NC}  ${GRAY}- :Implementation: should be in Python.${NC}              ${GRAY}│${NC}"
-echo -e "${GRAY}  │${NC}  ${GRAY}- :UnitTests: should use Unittest framework.${NC}         ${GRAY}│${NC}"
+echo -e "${GRAY}  │${NC}  ${GRAY}- :Implementation: should be in Python.${NC}               ${GRAY}│${NC}"
 echo -e "${GRAY}  │${NC}                                                        ${GRAY}│${NC}"
-echo -e "${GRAY}  │${NC}  ${GRAY}***test reqs***${NC}                                     ${GRAY}│${NC}"
+echo -e "${GRAY}  │${NC}  ${GRAY}***test reqs***${NC}                                       ${GRAY}│${NC}"
 echo -e "${GRAY}  │${NC}                                                        ${GRAY}│${NC}"
-echo -e "${GRAY}  │${NC}  ${GRAY}- :ConformanceTests: should use Unittest.${NC}            ${GRAY}│${NC}"
+echo -e "${GRAY}  │${NC}  ${GRAY}- :ConformanceTests: should use pytest.${NC}               ${GRAY}│${NC}"
 echo -e "${GRAY}  │${NC}                                                        ${GRAY}│${NC}"
-echo -e "${GRAY}  │${NC}  ${YELLOW}${BOLD}***functional specs***${NC}                               ${GRAY}│${NC}"
+echo -e "${GRAY}  │${NC}  ${YELLOW}${BOLD}***functional specs***${NC}                                ${GRAY}│${NC}"
 echo -e "${GRAY}  │${NC}                                                        ${GRAY}│${NC}"
-echo -e "${GRAY}  │${NC}  ${GREEN}${BOLD}- :App: should display \"hello, world\".${NC}               ${GRAY}│${NC}"
+echo -e "${GRAY}  │${NC}  ${GREEN}${BOLD}- :App: should display \"hello, world\".${NC}                ${GRAY}│${NC}"
 echo -e "${GRAY}  │${NC}                                                        ${GRAY}│${NC}"
 echo -e "${GRAY}  └────────────────────────────────────────────────────────┘${NC}"
 echo ""
@@ -79,37 +78,36 @@ read -r -p "  press [Enter] to continue..." < /dev/tty
 # Onboarding Step 3: Definitions
 clear
 echo ""
-echo -e "${GRAY}────────────────────────────────────────────${NC}"
-echo -e "  ${YELLOW}${BOLD}Plain Language 101${NC} - Step 3 of 5"
-echo -e "${GRAY}────────────────────────────────────────────${NC}"
+echo -e "${GRAY}─────────────────────────────────────────────────────────${NC}"
+echo -e "  ${YELLOW}${BOLD}***plain specification language intro${NC} - Step 3 of 5"
+echo -e "${GRAY}─────────────────────────────────────────────────────────${NC}"
 echo ""
-echo -e "  ${WHITE}${BOLD}DEFINITIONS${NC} - identify key concepts"
+echo -e "  ${WHITE}${BOLD}DEFINITIONS${NC} - definitions and descriptions of key concepts"
 echo ""
-echo -e "  Define ${GREEN}reusable concepts${NC} with the ${YELLOW}:ConceptName:${NC} syntax."
+echo -e "  Define ${GREEN}reusable concepts${NC} using the ${YELLOW}:Concept:${NC} notation."
 echo -e "  These become building blocks you can reference anywhere."
 echo ""
 echo -e "${GRAY}  ┌────────────────────────────────────────────────────────┐${NC}"
 echo -e "${GRAY}  │${NC}                                                        ${GRAY}│${NC}"
-echo -e "${GRAY}  │${NC}  ${YELLOW}${BOLD}***definitions***${NC}                                    ${GRAY}│${NC}"
+echo -e "${GRAY}  │${NC}  ${YELLOW}${BOLD}***definitions***${NC}                                     ${GRAY}│${NC}"
 echo -e "${GRAY}  │${NC}                                                        ${GRAY}│${NC}"
-echo -e "${GRAY}  │${NC}  ${GREEN}${BOLD}- :App: is a console application.${NC}                    ${GRAY}│${NC}"
+echo -e "${GRAY}  │${NC}  ${GREEN}${BOLD}- :App: is a console application.${NC}                     ${GRAY}│${NC}"
 echo -e "${GRAY}  │${NC}                                                        ${GRAY}│${NC}"
-echo -e "${GRAY}  │${NC}  ${GRAY}***implementation reqs***${NC}                                ${GRAY}│${NC}"
+echo -e "${GRAY}  │${NC}  ${GRAY}***implementation reqs***${NC}                             ${GRAY}│${NC}"
 echo -e "${GRAY}  │${NC}                                                        ${GRAY}│${NC}"
-echo -e "${GRAY}  │${NC}  ${GRAY}- :Implementation: should be in Python.${NC}              ${GRAY}│${NC}"
-echo -e "${GRAY}  │${NC}  ${GRAY}- :UnitTests: should use Unittest framework.${NC}         ${GRAY}│${NC}"
+echo -e "${GRAY}  │${NC}  ${GRAY}- :Implementation: should be in Python.${NC}               ${GRAY}│${NC}"
 echo -e "${GRAY}  │${NC}                                                        ${GRAY}│${NC}"
-echo -e "${GRAY}  │${NC}  ${GRAY}***test reqs***${NC}                                     ${GRAY}│${NC}"
+echo -e "${GRAY}  │${NC}  ${GRAY}***test reqs***${NC}                                       ${GRAY}│${NC}"
 echo -e "${GRAY}  │${NC}                                                        ${GRAY}│${NC}"
-echo -e "${GRAY}  │${NC}  ${GRAY}- :ConformanceTests: should use Unittest.${NC}            ${GRAY}│${NC}"
+echo -e "${GRAY}  │${NC}  ${GRAY}- :ConformanceTests: should use pytest.${NC}               ${GRAY}│${NC}"
 echo -e "${GRAY}  │${NC}                                                        ${GRAY}│${NC}"
-echo -e "${GRAY}  │${NC}  ${GRAY}***functional specs***${NC}                               ${GRAY}│${NC}"
+echo -e "${GRAY}  │${NC}  ${GRAY}***functional specs***${NC}                                ${GRAY}│${NC}"
 echo -e "${GRAY}  │${NC}                                                        ${GRAY}│${NC}"
-echo -e "${GRAY}  │${NC}  ${GRAY}- :App: should display \"hello, world\".${NC}               ${GRAY}│${NC}"
+echo -e "${GRAY}  │${NC}  ${GRAY}- :App: should display \"hello, world\".${NC}                ${GRAY}│${NC}"
 echo -e "${GRAY}  │${NC}                                                        ${GRAY}│${NC}"
 echo -e "${GRAY}  └────────────────────────────────────────────────────────┘${NC}"
 echo ""
-echo -e "  ${GREEN}▲${NC} The ${YELLOW}:App:${NC} concept is defined once and used throughout."
+echo -e "  ${GREEN}▲${NC} The ${YELLOW}:App:${NC} concept is defined once and used throughout the specs."
 echo -e "    Concepts help keep your specs consistent and clear."
 echo ""
 read -r -p "  press [Enter] to continue..." < /dev/tty
@@ -117,9 +115,9 @@ read -r -p "  press [Enter] to continue..." < /dev/tty
 # Onboarding Step 4: Implementation & Test Reqs
 clear
 echo ""
-echo -e "${GRAY}────────────────────────────────────────────${NC}"
-echo -e "  ${YELLOW}${BOLD}Plain Language 101${NC} - Step 4 of 5"
-echo -e "${GRAY}────────────────────────────────────────────${NC}"
+echo -e "${GRAY}─────────────────────────────────────────────────────────${NC}"
+echo -e "  ${YELLOW}${BOLD}***plain specification language intro${NC} - Step 4 of 5"
+echo -e "${GRAY}─────────────────────────────────────────────────────────${NC}"
 echo ""
 echo -e "  ${WHITE}${BOLD}IMPLEMENTATION & TEST REQS${NC} - how to implement and test"
 echo ""
@@ -128,22 +126,21 @@ echo -e "  This guides how the code should be generated and verified."
 echo ""
 echo -e "${GRAY}  ┌────────────────────────────────────────────────────────┐${NC}"
 echo -e "${GRAY}  │${NC}                                                        ${GRAY}│${NC}"
-echo -e "${GRAY}  │${NC}  ${GRAY}***definitions***${NC}                                    ${GRAY}│${NC}"
+echo -e "${GRAY}  │${NC}  ${GRAY}***definitions***${NC}                                     ${GRAY}│${NC}"
 echo -e "${GRAY}  │${NC}                                                        ${GRAY}│${NC}"
-echo -e "${GRAY}  │${NC}  ${GRAY}- :App: is a console application.${NC}                    ${GRAY}│${NC}"
+echo -e "${GRAY}  │${NC}  ${GRAY}- :App: is a console application.${NC}                     ${GRAY}│${NC}"
 echo -e "${GRAY}  │${NC}                                                        ${GRAY}│${NC}"
-echo -e "${GRAY}  │${NC}  ${YELLOW}${BOLD}***implementation reqs***${NC}                                ${GRAY}│${NC}"
+echo -e "${GRAY}  │${NC}  ${YELLOW}${BOLD}***implementation reqs***${NC}                             ${GRAY}│${NC}"
 echo -e "${GRAY}  │${NC}                                                        ${GRAY}│${NC}"
-echo -e "${GRAY}  │${NC}  ${GREEN}${BOLD}- :Implementation: should be in Python.${NC}              ${GRAY}│${NC}"
-echo -e "${GRAY}  │${NC}  ${GREEN}${BOLD}- :UnitTests: should use Unittest framework.${NC}         ${GRAY}│${NC}"
+echo -e "${GRAY}  │${NC}  ${GREEN}${BOLD}- :Implementation: should be in Python.${NC}               ${GRAY}│${NC}"
 echo -e "${GRAY}  │${NC}                                                        ${GRAY}│${NC}"
-echo -e "${GRAY}  │${NC}  ${YELLOW}${BOLD}***test reqs***${NC}                                     ${GRAY}│${NC}"
+echo -e "${GRAY}  │${NC}  ${YELLOW}${BOLD}***test reqs***${NC}                                       ${GRAY}│${NC}"
 echo -e "${GRAY}  │${NC}                                                        ${GRAY}│${NC}"
-echo -e "${GRAY}  │${NC}  ${GREEN}${BOLD}- :ConformanceTests: should use Unittest.${NC}            ${GRAY}│${NC}"
+echo -e "${GRAY}  │${NC}  ${GREEN}${BOLD}- :ConformanceTests: should use pytest.${NC}               ${GRAY}│${NC}"
 echo -e "${GRAY}  │${NC}                                                        ${GRAY}│${NC}"
-echo -e "${GRAY}  │${NC}  ${GRAY}***functional specs***${NC}                               ${GRAY}│${NC}"
+echo -e "${GRAY}  │${NC}  ${GRAY}***functional specs***${NC}                                ${GRAY}│${NC}"
 echo -e "${GRAY}  │${NC}                                                        ${GRAY}│${NC}"
-echo -e "${GRAY}  │${NC}  ${GRAY}- :App: should display \"hello, world\".${NC}               ${GRAY}│${NC}"
+echo -e "${GRAY}  │${NC}  ${GRAY}- :App: should display \"hello, world\".${NC}                ${GRAY}│${NC}"
 echo -e "${GRAY}  │${NC}                                                        ${GRAY}│${NC}"
 echo -e "${GRAY}  └────────────────────────────────────────────────────────┘${NC}"
 echo ""
@@ -155,9 +152,9 @@ read -r -p "  press [Enter] to continue..." < /dev/tty
 # Onboarding Step 5: Rendering Code
 clear
 echo ""
-echo -e "${GRAY}────────────────────────────────────────────${NC}"
-echo -e "  ${YELLOW}${BOLD}Plain Language 101${NC} - Step 5 of 5"
-echo -e "${GRAY}────────────────────────────────────────────${NC}"
+echo -e "${GRAY}─────────────────────────────────────────────────────────${NC}"
+echo -e "  ${YELLOW}${BOLD}***plain specification language intro${NC} - Step 5 of 5"
+echo -e "${GRAY}─────────────────────────────────────────────────────────${NC}"
 echo ""
 echo -e "  ${WHITE}${BOLD}RENDERING CODE${NC} - generate your app"
 echo ""

{codeplain-0.2.6 → codeplain-0.2.8}/module_renderer.py

@@ -260,4 +260,11 @@ class ModuleRenderer:
         self.loaded_modules = list[PlainModule]()
         _, _, rendering_failed = self._render_module(self.filename, self.render_range, True)
         if not rendering_failed:
-            self.event_bus.publish(RenderCompleted())
+            # Get the last module that completed rendering
+            if self.args.copy_build:
+                rendered_code_path = f"{self.args.build_dest}/"
+            else:
+                last_module_name = self.filename.replace(plain_file.PLAIN_SOURCE_FILE_EXTENSION, "")
+                rendered_code_path = f"{os.path.join(self.args.build_folder, last_module_name)}/"
+
+            self.event_bus.publish(RenderCompleted(rendered_code_path=rendered_code_path))

{codeplain-0.2.6 → codeplain-0.2.8}/plain2code.py

@@ -3,6 +3,7 @@ import logging
 import logging.config
 import os
 import sys
+from pathlib import Path
 from typing import Optional
 
 import yaml
@@ -42,6 +43,7 @@ from plain2code_logger import (
     get_log_file_path,
 )
 from plain2code_state import RunState
+from plain2code_utils import print_dry_run_output
 from system_config import system_config
 from tui.plain2code_tui import Plain2CodeTUI
 
@@ -72,6 +74,23 @@ def get_render_range_from(start, plain_source):
     return _get_frids_range(plain_source, start)
 
 
+def compute_render_range(args, plain_source_tree):
+    """Compute render range from --render-range or --render-from arguments.
+
+    Args:
+        args: Parsed command line arguments
+        plain_source_tree: Parsed plain source tree
+
+    Returns:
+        List of FRIDs to render, or None to render all
+    """
+    if args.render_range:
+        return get_render_range(args.render_range, plain_source_tree)
+    elif args.render_from:
+        return get_render_range_from(args.render_from, plain_source_tree)
+    return None
+
+
 def _get_frids_range(plain_source, start, end=None):
     frids = list(plain_spec.get_frids(plain_source))
 
@@ -196,11 +215,7 @@ def render(args, run_state: RunState, event_bus: EventBus):  # noqa: C901
     if args.render_range or args.render_from:
         # Parse the plain file to get the plain_source for FRID extraction
         _, plain_source, _ = plain_file.plain_file_parser(args.filename, template_dirs)
-
-        if args.render_range:
-            render_range = get_render_range(args.render_range, plain_source)
-        elif args.render_from:
-            render_range = get_render_range_from(args.render_from, plain_source)
+        render_range = compute_render_range(args, plain_source)
 
     codeplainAPI = codeplain_api.CodeplainAPI(args.api_key, console)
     codeplainAPI.verbose = args.verbose
@@ -242,6 +257,29 @@ def render(args, run_state: RunState, event_bus: EventBus):  # noqa: C901
 def main():  # noqa: C901
     args = parse_arguments()
 
+    # Handle early-exit flags before heavy initialization
+    if args.dry_run or args.full_plain:
+        template_dirs = file_utils.get_template_directories(args.filename, args.template_dir, DEFAULT_TEMPLATE_DIRS)
+
+        try:
+            if args.full_plain:
+                module_name = Path(args.filename).stem
+                plain_source = plain_file.read_module_plain_source(module_name, template_dirs)
+                [full_plain_source, _] = file_utils.get_loaded_templates(template_dirs, plain_source)
+                console.info("Full plain text:\n")
+                console.info(full_plain_source)
+                return
+
+            if args.dry_run:
+                console.info("Printing dry run output...\n")
+                _, plain_source_tree, _ = plain_file.plain_file_parser(args.filename, template_dirs)
+                render_range = compute_render_range(args, plain_source_tree)
+                print_dry_run_output(plain_source_tree, render_range)
+                return
+        except Exception as e:
+            console.error(f"Error: {str(e)}")
+            return
+
     event_bus = EventBus()
 
     if not args.api:

{codeplain-0.2.6 → codeplain-0.2.8}/plain2code_arguments.py

@@ -15,6 +15,7 @@ DEFAULT_CONFORMANCE_TESTS_DEST = "dist_conformance_tests"
 UNIT_TESTS_SCRIPT_NAME = "unittests_script"
 CONFORMANCE_TESTS_SCRIPT_NAME = "conformance_tests_script"
 DEFAULT_LOG_FILE_NAME = "codeplain.log"
+PREPARE_ENVIRONMENT_SCRIPT_NAME = "prepare_environment_script"
 
 
 def process_test_script_path(script_arg_name, config):
@@ -134,7 +135,7 @@ def create_parser():
         "--log-to-file",
         action=argparse.BooleanOptionalAction,
         default=True,
-        help="Enable logging to a file. Defaults to True. Use --no-log-to-file to disable.",
+        help="Enable logging to a file. Defaults to True. Set to False to disable.",
     )
     parser.add_argument(
         "--log-file-name",
@@ -142,7 +143,7 @@ def create_parser():
         default=DEFAULT_LOG_FILE_NAME,
         help=f"Name of the log file. Defaults to '{DEFAULT_LOG_FILE_NAME}'."
         "Always resolved relative to the plain file directory."
-        "If file on this path already exists, it will be overwritten by the current logs.",
+        "If file on this path already exists, the already existing log file will be overwritten by the current logs.",
     )
 
     # Add config file arguments
@@ -158,14 +159,14 @@ def create_parser():
     render_range_group.add_argument(
         "--render-range",
         type=frid_range_string,
-        help="Specify a range of functional requirements to render (e.g. '1.1,2.3'). "
+        help="Specify a range of functional requirements to render (e.g. `1` , `2`, `3`). "
         "Use comma to separate start and end IDs. If only one ID is provided, only that requirement is rendered. "
         "Range is inclusive of both start and end IDs.",
     )
     render_range_group.add_argument(
         "--render-from",
         type=frid_string,
-        help="Continue generation starting from this specific functional requirement (e.g. '2.1'). "
+        help="Continue generation starting from this specific functional requirement (e.g. `2`). "
         "The requirement with this ID will be included in the output. The ID must match one of the functional requirements in your plain file.",
     )
 
@@ -190,15 +191,15 @@ def create_parser():
     parser.add_argument(
         "--conformance-tests-script",
         type=str,
-        help="Path to conformance tests shell script. The script should accept two arguments: "
-        "1) First argument: path to a folder (e.g. 'plain_modules/module_name') containing generated source code, "
-        "2) Second argument: path to a subfolder of the conformance tests folder (e.g. 'conformance_tests/subfoldername') containing test files.",
+        help="Path to conformance tests shell script. Every conformance test script should accept two arguments: "
+        "1) Path to a folder (e.g. `plain_modules/module_name`) containing generated source code, "
+        "2) Path to a subfolder of the conformance tests folder (e.g. `conformance_tests/subfoldername`) containing test files.",
     )
 
     parser.add_argument(
         "--prepare-environment-script",
         type=str,
-        help="Path to a shell script that prepares the testing environment. The script should accept the build folder path as its first argument (default: 'plain_modules').",
+        help="Path to a shell script that prepares the testing environment. The script should accept the source code folder path as its first argument.",
     )
 
     parser.add_argument(
@@ -212,17 +213,18 @@ def create_parser():
         "--api-key",
         type=str,
         default=CODEPLAIN_API_KEY,
-        help="API key used to access the API. If not provided, the CODEPLAIN_API_KEY environment variable is used.",
+        help="API key used to access the API. If not provided, the `CODEPLAIN_API_KEY` environment variable is used.",
     )
     parser.add_argument(
         "--full-plain",
         action="store_true",
-        help="Display the complete plain specification before code generation. "
-        "This shows your plain file with "
-        "any included template content expanded. Useful for understanding what content is being processed.",
+        help="Full preview ***plain specification before code generation."
+        "Use when you want to preview context of all ***plain primitives that are going to be included in order to render the given module.",
     )
     parser.add_argument(
-        "--dry-run", action="store_true", help="Preview of what Codeplain would do without actually making any changes."
+        "--dry-run",
+        action="store_true",
+        help="Dry run preview of the code generation (without actually making any changes).",
     )
     parser.add_argument(
         "--replay-with",
@@ -236,33 +238,33 @@ def create_parser():
         type=str,
         default=None,
         help="Path to a custom template directory. Templates are searched in the following order: "
-        "1) directory containing the plain file, "
-        "2) this custom template directory (if provided), "
-        "3) built-in standard_template_library directory",
+        "1) Directory containing the plain file, "
+        "2) Custom template directory (if provided through this argument), "
+        "3) Built-in standard_template_library directory",
     )
     parser.add_argument(
         "--copy-build",
         action="store_true",
         default=False,
-        help="If set, copy the build folder to `--build-dest` after every successful rendering.",
+        help="If set, copy the rendered contents of code in `--base-folder` folder to `--build-dest` folder after successful rendering.",
     )
     parser.add_argument(
         "--build-dest",
         type=non_empty_string,
         default=DEFAULT_BUILD_DEST,
-        help="Target folder to copy build output to (used only if --copy-build is set).",
+        help="Target folder to copy rendered contents of code to (used only if --copy-build is set).",
     )
     parser.add_argument(
         "--copy-conformance-tests",
         action="store_true",
         default=False,
-        help="If set, copy the conformance tests folder to `--conformance-tests-dest` after every successful rendering. Requires --conformance-tests-script.",
+        help="If set, copy the conformance tests of code in `--conformance-tests-folder` folder to `--conformance-tests-dest` folder successful rendering. Requires --conformance-tests-script.",
     )
     parser.add_argument(
         "--conformance-tests-dest",
         type=non_empty_string,
         default=DEFAULT_CONFORMANCE_TESTS_DEST,
-        help="Target folder to copy conformance tests output to (used only if --copy-conformance-tests is set).",
+        help="Target folder to copy conformance tests of code to (used only if --copy-conformance-tests is set).",
     )
 
     parser.add_argument(
@@ -301,7 +303,10 @@ def parse_arguments():
     if not args.log_to_file and args.log_file_name != DEFAULT_LOG_FILE_NAME:
         parser.error("--log-file-name cannot be used when --log-to-file is False.")
 
-    script_arg_names = [UNIT_TESTS_SCRIPT_NAME, CONFORMANCE_TESTS_SCRIPT_NAME]
+    if args.full_plain and args.dry_run:
+        parser.error("--full-plain and --dry-run are mutually exclusive")
+
+    script_arg_names = [UNIT_TESTS_SCRIPT_NAME, CONFORMANCE_TESTS_SCRIPT_NAME, PREPARE_ENVIRONMENT_SCRIPT_NAME]
     for script_name in script_arg_names:
         args = process_test_script_path(script_name, args)
 

{codeplain-0.2.6 → codeplain-0.2.8}/plain2code_events.py

@@ -24,10 +24,11 @@ class RenderContextSnapshot:
     module_name: str
 
 
+@dataclass
 class RenderCompleted(BaseEvent):
     """Event emitted when rendering completes successfully."""
 
-    pass
+    rendered_code_path: str
 
 
 @dataclass

{codeplain-0.2.6 → codeplain-0.2.8}/plain2code_utils.py

@@ -22,14 +22,14 @@ def print_dry_run_output(plain_source_tree: dict, render_range: Optional[list[st
             specifications, _ = plain_spec.get_specifications_for_frid(plain_source_tree, frid)
             functional_requirement_text = specifications[plain_spec.FUNCTIONAL_REQUIREMENTS][-1]
             console.info(
-                "-------------------------------------"
-                f"Rendering functional requirement {frid}"
-                f"{functional_requirement_text}"
-                "-------------------------------------"
+                "-------------------------------------\n"
+                f"Rendering functional requirement {frid}\n"
+                f"{functional_requirement_text}\n"
+                "-------------------------------------\n"
             )
             if plain_spec.ACCEPTANCE_TESTS in specifications:
                 for i, acceptance_test in enumerate(specifications[plain_spec.ACCEPTANCE_TESTS], 1):
-                    console.info(f"Generating acceptance test #{i}:\n\n{acceptance_test}")
+                    console.info(f"Generating acceptance test #{i}:\n\n{acceptance_test}\n")
         else:
             console.info(
                 "-------------------------------------\n"

{codeplain-0.2.6 → codeplain-0.2.8}/pyproject.toml

@@ -4,10 +4,10 @@ build-backend = "hatchling.build"
 
 [project]
 name = "codeplain"
-version = "0.2.6"
+version = "0.2.8"
 description = "Transform plain language specifications into working code"
 readme = "README.md"
-requires-python = ">=3.11"
+requires-python = "~=3.11.0"
 classifiers = [
     "Environment :: Console",
     "Intended Audience :: Developers",