codeplain 0.3.8__tar.gz → 0.3.9__tar.gz

{codeplain-0.3.8 → codeplain-0.3.9}/.github/workflows/publish-install-script.yml

@@ -14,6 +14,9 @@ jobs:
     name: Upload to Cloudflare R2
     runs-on: ubuntu-latest
 
+    env:
+      SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
+
     steps:
       - uses: actions/checkout@v4
 
@@ -54,3 +57,17 @@ jobs:
             --content-type "text/plain"
           echo "✓ examples.ps1 uploaded to R2"
 
+      - name: Notify Slack (success)
+        if: ${{ success() && env.SLACK_WEBHOOK_URL != '' }}
+        run: |
+          curl -s -X POST "$SLACK_WEBHOOK_URL" \
+            -H 'Content-type: application/json' \
+            --data "{\"text\":\"*Codeplain Client*: Install scripts deployed to R2 :white_check_mark: (\`${GITHUB_SHA:0:7}\`, by *${{ github.actor }}*).\"}"
+
+      - name: Notify Slack (failure)
+        if: ${{ failure() && env.SLACK_WEBHOOK_URL != '' }}
+        run: |
+          curl -s -X POST "$SLACK_WEBHOOK_URL" \
+            -H 'Content-type: application/json' \
+            --data "{\"text\":\"*Codeplain Client*: Install script deploy to R2 FAILED :x: (\`${GITHUB_SHA:0:7}\`). Users may be getting a stale installer. See <${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}|the run log>.\"}"
+

{codeplain-0.3.8 → codeplain-0.3.9}/.github/workflows/publish-to-pypi.yml

@@ -15,12 +15,22 @@ jobs:
     permissions:
       contents: write
 
+    env:
+      SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
+
     steps:
       - uses: actions/checkout@v4
         with:
           # hatch-vcs derives the version from git tags, so we need full history.
           fetch-depth: 0
 
+      - name: Notify Slack (start)
+        if: ${{ env.SLACK_WEBHOOK_URL != '' }}
+        run: |
+          curl -s -X POST "$SLACK_WEBHOOK_URL" \
+            -H 'Content-type: application/json' \
+            --data "{\"text\":\"*Codeplain Client*: Release \`${{ github.ref_name }}\` published by *${{ github.actor }}* — building and publishing to PyPI...\"}"
+
       - name: Install uv
         # uv provisions its own Python (honoring requires-python), so no
         # separate actions/setup-python step is needed.
@@ -47,6 +57,13 @@ jobs:
         run: |
           gh release upload ${{ github.ref_name }} dist/* --clobber
 
+      - name: Notify Slack (build failure)
+        if: ${{ failure() && env.SLACK_WEBHOOK_URL != '' }}
+        run: |
+          curl -s -X POST "$SLACK_WEBHOOK_URL" \
+            -H 'Content-type: application/json' \
+            --data "{\"text\":\"*Codeplain Client*: Build of \`${{ github.ref_name }}\` FAILED :x:. Nothing was published to PyPI. See <${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}|the run log>.\"}"
+
   publish-to-pypi:
     name: Publish to PyPI
     needs: build
@@ -59,6 +76,9 @@ jobs:
       # authenticate this run — no long-lived API token needed.
       id-token: write
 
+    env:
+      SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
+
     steps:
       - name: Download distribution packages
         uses: actions/download-artifact@v4
@@ -68,3 +88,17 @@ jobs:
 
       - name: Publish to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Notify Slack (success)
+        if: ${{ success() && env.SLACK_WEBHOOK_URL != '' }}
+        run: |
+          curl -s -X POST "$SLACK_WEBHOOK_URL" \
+            -H 'Content-type: application/json' \
+            --data "{\"text\":\"*Codeplain Client*: \`${{ github.ref_name }}\` published to PyPI :white_check_mark:. Install with \`pip install --upgrade codeplain\`.\"}"
+
+      - name: Notify Slack (failure)
+        if: ${{ failure() && env.SLACK_WEBHOOK_URL != '' }}
+        run: |
+          curl -s -X POST "$SLACK_WEBHOOK_URL" \
+            -H 'Content-type: application/json' \
+            --data "{\"text\":\"*Codeplain Client*: Publishing \`${{ github.ref_name }}\` to PyPI FAILED :x:. See <${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}|the run log>.\"}"

{codeplain-0.3.8 → codeplain-0.3.9}/CLAUDE.md

@@ -212,8 +212,12 @@ Two logging modes:
 ### Code Generation Process
 - Templates in `standard_template_library/` use Liquid2 syntax
 - Template search order: (1) `.plain` file dir, (2) `--template-dir`, (3) built-in standard lib
-- Generated code written to `build/` (configurable via `--build-folder`)
-- Each FRID render produces a git commit in build folder for rollback capability
+- Each module renders into its own tree under the build folder (configurable via `--build-folder`, default `plain_modules/`):
+  - `<build-folder>/<module>/code/` — implementation code (its own git repo)
+  - `<build-folder>/<module>/tests/` — conformance tests (its own git repo; only created when a conformance tests script is configured)
+  - `<build-folder>/<module>/.codeplain/` — module metadata (`module_metadata.json`), not tracked in git
+  - `<build-folder>/<module>/.memory/` — conformance test memory, not tracked in git
+- Each FRID render produces a git commit in the `code/` and `tests/` repos for rollback capability
 
 ### Configuration
 - `config.yaml` can be placed in `.plain` file dir or CWD

{codeplain-0.3.8 → codeplain-0.3.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codeplain
-Version: 0.3.8
+Version: 0.3.9
 Summary: Transform plain language specifications into working code
 License-File: LICENSE
 Classifier: Environment :: Console

{codeplain-0.3.8 → codeplain-0.3.9}/docs/plain2code_cli.md

@@ -9,7 +9,6 @@ usage: generate_cli.py [-h] [--verbose] [--base-folder BASE_FOLDER]
                        [--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]
                        [--test-script-timeout TEST_SCRIPT_TIMEOUT]
@@ -20,8 +19,8 @@ usage: generate_cli.py [-h] [--verbose] [--base-folder BASE_FOLDER]
                        [--conformance-tests-dest CONFORMANCE_TESTS_DEST]
                        [--render-machine-graph]
                        [--logging-config-path LOGGING_CONFIG_PATH]
-                       [--headless]
-                       filename
+                       [--headless] [--status] [--version]
+                       [filename]
 
 Render plain code to target code. Path arguments resolve based on where they
 were written: values given on the command line are resolved against the
@@ -39,7 +38,7 @@ positional arguments:
 
 options:
   -h, --help            show this help message and exit
-  --verbose, -v         Enable verbose output
+  --verbose, -v         Set default log level to DEBUG for TUI and file logs
   --base-folder BASE_FOLDER
                         Base folder for the build files
   --build-folder BUILD_FOLDER
@@ -66,18 +65,17 @@ options:
   --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
+                        Receives the module's code folder path as its first
+                        argument (e.g. `plain_modules/module_name/code`).
   --conformance-tests-script CONFORMANCE_TESTS_SCRIPT
                         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.
+                        1) Path to a folder (e.g.
+                        `plain_modules/module_name/code`) containing generated
+                        source code, 2) Path to a subfolder of the module's
+                        tests folder (e.g.
+                        `plain_modules/module_name/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 source code
@@ -90,9 +88,9 @@ options:
   --api-key API_KEY     API key used to access the API. If not provided, the
                         `CODEPLAIN_API_KEY` environment variable is used.
   --full-plain          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.
+                        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.
   --dry-run             Dry run preview of the code generation (without
                         actually making any changes).
   --replay-with REPLAY_WITH
@@ -109,10 +107,10 @@ options:
                         Target folder to copy rendered contents of code to
                         (used only if --copy-build is set).
   --copy-conformance-tests
-                        If set, copy the conformance tests of code in
-                        `--conformance-tests-folder` folder to `--conformance-
-                        tests-dest` folder successful rendering. Requires
-                        --conformance-tests-script.
+                        If set, copy the module's conformance tests (from
+                        `<build-folder>/<module>/tests`) to `--conformance-
+                        tests-dest` folder after successful rendering.
+                        Requires --conformance-tests-script.
   --conformance-tests-dest CONFORMANCE_TESTS_DEST
                         Target folder to copy conformance tests of code to
                         (used only if --copy-conformance-tests is set).
@@ -123,6 +121,10 @@ options:
   --headless            Run in headless mode: no TUI, no terminal output
                         except a single render-started message. All logs are
                         written to the log file.
+  --status              Display account status including user information, API
+                        key label, and rendering credits. Does not render any
+                        code.
+  --version             Display the client version and exit.
 
 configuration:
   --config-name CONFIG_NAME

{codeplain-0.3.8 → codeplain-0.3.9}/docs/starting_a_plain_project_from_scratch.md

@@ -22,10 +22,16 @@ my-new-project/
 ├── run_unittests_[language].sh         # Unit test script
 ├── run_conformance_tests_[language].sh # Conformance test script
 ├── build/                              # Generated final code
-├── plain_modules/                      # Generated modules code
-└── conformance_tests/                  # Generated conformanece tests code
+└── plain_modules/                      # Generated modules
+    └── my_app/                         # One folder per module
+        ├── .codeplain/                 # Module metadata
+        ├── .memory/                    # Conformance test memory
+        ├── code/                       # Generated code
+        └── tests/                      # Generated conformance tests
 ```
 
+The `tests/` folder is only created when a conformance test script is configured.
+
 In this guide we will cover how to create each of these step by step.
 
 ## 1. Define Your .plain File

{codeplain-0.3.8 → codeplain-0.3.9}/examples/example_hello_world_golang/run.sh

@@ -20,11 +20,11 @@ if [ $? -ne 0 ]; then
     exit 1
 fi
 
-cd plain_modules/hello_world_golang
+cd plain_modules/hello_world_golang/code
 
 # We need to compile the tests so that we can execute them in the current folder
 # (https://stackoverflow.com/questions/23847003/golang-tests-and-working-directory/29541248#29541248)
-go test -c ../../harness_tests/hello_world_test.go
+go test -c ../../../harness_tests/hello_world_test.go
 
 # Check if test compilation has failed for the hello world example
 if [ $? -ne 0 ]; then

{codeplain-0.3.8 → codeplain-0.3.9}/examples/example_hello_world_python/run.sh

@@ -7,9 +7,9 @@ if [ $? -ne 0 ]; then
     exit 1
 fi
 
-cd plain_modules/hello_world_python
+cd plain_modules/hello_world_python/code
 
-python ../../harness_tests/hello_world_display/test_hello_world.py
+python ../../../harness_tests/hello_world_display/test_hello_world.py
 
 # Check if the test harness has failed for the hello world example
 if [ $? -ne 0 ]; then

{codeplain-0.3.8 → codeplain-0.3.9}/examples/example_hello_world_react/run.sh

@@ -20,7 +20,7 @@ if [ $? -ne 0 ]; then
     exit 1
 fi
 
-../../test_scripts/run_conformance_tests_cypress.sh plain_modules/hello_world_react harness_tests/hello_world_display ${VERBOSE:+-v}
+../../test_scripts/run_conformance_tests_cypress.sh plain_modules/hello_world_react/code harness_tests/hello_world_display ${VERBOSE:+-v}
 
 # Check if the test harness has failed for the hello world example
 if [ $? -ne 0 ]; then

{codeplain-0.3.8 → codeplain-0.3.9}/git_utils.py

@@ -64,7 +64,6 @@ def init_git_repo(
     path_to_repo: Union[str, os.PathLike],
     module_name: Optional[str] = None,
     render_id: Optional[str] = None,
-    initial_files: Optional[dict[str, str]] = None,
 ) -> Repo:
     """
     Initializes a new git repository in the given path.
@@ -79,10 +78,6 @@ def init_git_repo(
     repo = Repo.init(path_to_repo)
     _ensure_git_config(repo)
 
-    if initial_files:
-        file_utils.store_response_files(path_to_repo, initial_files, [])
-        repo.git.add(".")
-
     repo.git.commit(
         "--allow-empty", "-m", _get_full_commit_message(INITIAL_COMMIT_MESSAGE, module_name, None, render_id)
     )
@@ -95,14 +90,9 @@ def clone_repo(
     new_repo_path: str,
     module_name: Optional[str] = None,
     render_id: Optional[str] = None,
-    initial_files: Optional[dict[str, str]] = None,
 ) -> Repo:
     repo = Repo.clone_from(source_repo_path, new_repo_path)
 
-    if initial_files:
-        file_utils.store_response_files(new_repo_path, initial_files, [])
-        repo.git.add(".")
-
     repo.git.commit(
         "--allow-empty", "-m", _get_full_commit_message(INITIAL_COMMIT_MESSAGE, module_name, None, render_id)
     )

{codeplain-0.3.8 → codeplain-0.3.9}/memory_management.py

@@ -3,7 +3,6 @@ import os
 
 import file_utils
 from plain2code_console import console
-from plain_modules import CODEPLAIN_MEMORY_SUBFOLDER
 from render_machine.implementation_code_helpers import ImplementationCodeHelpers
 from render_machine.render_context import RenderContext
 
@@ -24,9 +23,9 @@ class MemoryManager:
         console.debug(f"Loaded {len(memory_files_content)} memory files.")
         return memory_files, memory_files_content
 
-    def __init__(self, codeplain_api, module_name: str, conformance_tests_folder: str):
+    def __init__(self, codeplain_api, memory_folder: str):
         self.codeplain_api = codeplain_api
-        self.memory_folder = os.path.join(conformance_tests_folder, module_name, CODEPLAIN_MEMORY_SUBFOLDER)
+        self.memory_folder = memory_folder
 
     def create_conformance_tests_memory(
         self, render_context: RenderContext, exit_code: int, conformance_tests_issue: str

codeplain-0.3.9/metadata_utils.py

@@ -0,0 +1,46 @@
+"""Read/write helpers for the per-module metadata file (``module_metadata.json``).
+
+These helpers operate purely on a metadata path or a plain dict. Module-specific
+logic — computing the hashes, assembling the payload from the spec and required
+modules — stays on :class:`plain_modules.PlainModule`.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+
+MODULE_METADATA_FILENAME = "module_metadata.json"
+MODULE_FUNCTIONALITIES = "functionalities"
+REQUIRED_MODULES_FUNCTIONALITIES = "required_modules_functionalities"
+
+
+def load_metadata(metadata_path: str) -> dict | None:
+    """Return the parsed metadata dict, or None if the file does not exist."""
+    if not os.path.exists(metadata_path):
+        return None
+
+    with open(metadata_path, "r", encoding="utf-8") as f:
+        return json.load(f)
+
+
+def write_metadata(metadata_path: str, metadata: dict) -> None:
+    """Write metadata as indented JSON, creating the parent folder if needed."""
+    os.makedirs(os.path.dirname(metadata_path), exist_ok=True)
+
+    with open(metadata_path, "w", encoding="utf-8") as f:
+        json.dump(metadata, f, indent=4)
+
+
+def truncate_functionalities(metadata: dict, keep_count: int) -> bool:
+    """Trim the functionalities list in ``metadata`` in place to ``keep_count`` entries.
+
+    Returns True if the list was shortened, False if it was already short enough
+    (in which case ``metadata`` is left untouched).
+    """
+    functionalities = metadata.get(MODULE_FUNCTIONALITIES, [])
+    if len(functionalities) <= keep_count:
+        return False
+
+    metadata[MODULE_FUNCTIONALITIES] = functionalities[:keep_count]
+    return True

{codeplain-0.3.8 → codeplain-0.3.9}/module_renderer.py

@@ -1,5 +1,4 @@
 import argparse
-import os
 import threading
 
 from event_bus import EventBus
@@ -48,9 +47,8 @@ class ModuleRenderer:
             self.codeplainAPI,
             memory_manager,
             plain_module,
-            build_folder=os.path.join(self.args.build_folder, plain_module.module_name),
+            build_folder=plain_module.module_build_folder,
             build_dest=self.args.build_dest,
-            conformance_tests_folder=self.args.conformance_tests_folder,
             conformance_tests_dest=self.args.conformance_tests_dest,
             unittests_script=self.args.unittests_script,
             conformance_tests_script=self.args.conformance_tests_script,
@@ -115,8 +113,7 @@ class ModuleRenderer:
 
         memory_manager = MemoryManager(
             self.codeplainAPI,
-            plain_module.module_name,
-            self.args.conformance_tests_folder,
+            plain_module.module_memory_folder,
         )
         render_context = self._build_render_context_for_module(
             plain_module,
@@ -165,7 +162,7 @@ class ModuleRenderer:
             if self.args.copy_build:
                 rendered_code_path = f"{self.args.build_dest}/"
             else:
-                rendered_code_path = self.args.build_folder
+                rendered_code_path = self.plain_module.module_build_folder
 
             self.run_state.set_render_generated_code_path(rendered_code_path)
             self.event_bus.publish(RenderCompleted(rendered_code_path=rendered_code_path))

{codeplain-0.3.8 → codeplain-0.3.9}/plain2code.py

@@ -212,6 +212,12 @@ def render(  # noqa: C901
 
     warn_if_acceptance_tests_without_conformance_script(plain_module, args)
 
+    # The module_metadata file lives outside the code git repo. That means that a crash mid-render can leave it
+    # claiming a functionality was implemented even thought it wasn't yet committed (because of the crash).
+    # Out of precaution, this reconciles every module_metadata against the code repo.
+    for module in plain_module.all_required_modules + [plain_module]:
+        module.reconcile_metadata_with_git()
+
     render_choice = None
     if render_range is None:
         plain_module_render_state = get_plain_module_render_state(plain_module)
@@ -356,7 +362,6 @@ def main():  # noqa: C901
         plain_module = plain_modules.PlainModule(
             os.path.basename(args.filename),
             args.build_folder,
-            args.conformance_tests_folder,
             template_dirs,
         )
     except Exception as e:

{codeplain-0.3.8 → codeplain-0.3.9}/plain2code_arguments.py

@@ -16,7 +16,6 @@ CODEPLAIN_API_KEY = os.getenv("CODEPLAIN_API_KEY")
 
 
 DEFAULT_BUILD_FOLDER = "plain_modules"
-DEFAULT_CONFORMANCE_TESTS_FOLDER = "conformance_tests"
 DEFAULT_BUILD_DEST = "dist"
 DEFAULT_CONFORMANCE_TESTS_DEST = "dist_conformance_tests"
 
@@ -299,23 +298,15 @@ def create_parser():
         parser,
         "--unittests-script",
         type=str,
-        help="Shell script to run unit tests on generated code. Receives the build folder path as its first argument (default: 'plain_modules').",
-    )
-    _add_arg(
-        parser,
-        "--conformance-tests-folder",
-        type=non_empty_string,
-        default=DEFAULT_CONFORMANCE_TESTS_FOLDER,
-        help="Folder for conformance test files",
-        path=True,
+        help="Shell script to run unit tests on generated code. Receives the module's code folder path as its first argument (e.g. `plain_modules/module_name/code`).",
     )
     _add_arg(
         parser,
         "--conformance-tests-script",
         type=str,
         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.",
+        "1) Path to a folder (e.g. `plain_modules/module_name/code`) containing generated source code, "
+        "2) Path to a subfolder of the module's tests folder (e.g. `plain_modules/module_name/tests/subfoldername`) containing test files.",
     )
 
     _add_arg(
@@ -400,7 +391,7 @@ def create_parser():
         "--copy-conformance-tests",
         action="store_true",
         default=False,
-        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.",
+        help="If set, copy the module's conformance tests (from `<build-folder>/<module>/tests`) to `--conformance-tests-dest` folder after successful rendering. Requires --conformance-tests-script.",
     )
     _add_arg(
         parser,
@@ -490,8 +481,8 @@ def parse_arguments(command_line: Optional[Sequence[str]] = None):
 
     if args.build_folder == args.build_dest:
         parser.error("--build-folder and --build-dest cannot be the same")
-    if args.conformance_tests_folder == args.conformance_tests_dest:
-        parser.error("--conformance-tests-folder and --conformance-tests-dest cannot be the same")
+    if args.conformance_tests_dest == args.build_folder:
+        parser.error("--conformance-tests-dest and --build-folder cannot be the same")
 
     args.render_conformance_tests = args.conformance_tests_script is not None
 

{codeplain-0.3.8 → codeplain-0.3.9}/plain2code_cli.md

@@ -3,19 +3,19 @@
 ```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] [--test-script-timeout TEST_SCRIPT_TIMEOUT] [--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 LOGGING_CONFIG_PATH] [--headless] [--status] [--version]
+                       [--conformance-tests-script CONFORMANCE_TESTS_SCRIPT] [--prepare-environment-script PREPARE_ENVIRONMENT_SCRIPT] [--test-script-timeout TEST_SCRIPT_TIMEOUT]
+                       [--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 LOGGING_CONFIG_PATH] [--headless]
+                       [--status] [--version]
                        [filename]
 
-Render plain code to target code. Path arguments resolve based on where they were written: values given on the command line are resolved against the current working directory, values
-read from config.yaml are resolved against the config file's directory, and defaults are resolved against the directory containing the plain file. Absolute paths (and paths starting
-with '~') are used as-is.
+Render plain code to target code. Path arguments resolve based on where they were written: values given on the command line are resolved against the current working directory, values read
+from config.yaml are resolved against the config file's directory, and defaults are resolved against the directory containing the plain file. Absolute paths (and paths starting with '~')
+are used as-is.
 
 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.
+  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
@@ -32,24 +32,22 @@ with '~') are used as-is.
                         Specify a range of functionalities to render (e.g. `1` , `2`, `3`). Use comma to separate start and end IDs. If only one functionality ID is provided, only that
                         functionality is rendered. Range is inclusive of both start and end IDs.
   --render-from RENDER_FROM
-                        Continue generation starting from this specific functionality (e.g. `2`). The functionality with this ID will be included in the output. The functionality ID
-                        must match one of the functionalities in your plain file.
+                        Continue generation starting from this specific functionality (e.g. `2`). The functionality with this ID will be included in the output. The functionality ID must
+                        match one of the functionalities 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
+                        Shell script to run unit tests on generated code. Receives the module's code folder path as its first argument (e.g. `plain_modules/module_name/code`).
   --conformance-tests-script CONFORMANCE_TESTS_SCRIPT
-                        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.
+                        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/code`)
+                        containing generated source code, 2) Path to a subfolder of the module's tests folder (e.g. `plain_modules/module_name/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 source code folder path as its first argument.
   --test-script-timeout TEST_SCRIPT_TIMEOUT
                         Timeout for test scripts in seconds. If not provided, the default timeout of 120 seconds is used.
   --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          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.
+  --full-plain          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.
   --dry-run             Dry run preview of the code generation (without actually making any changes).
   --replay-with REPLAY_WITH
   --template-dir TEMPLATE_DIR
@@ -59,7 +57,7 @@ with '~') are used as-is.
   --build-dest BUILD_DEST
                         Target folder to copy rendered contents of code to (used only if --copy-build is set).
   --copy-conformance-tests
-                        If set, copy the conformance tests of code in `--conformance-tests-folder` folder to `--conformance-tests-dest` folder successful rendering. Requires
+                        If set, copy the module's conformance tests (from `<build-folder>/<module>/tests`) to `--conformance-tests-dest` folder after successful rendering. Requires
                         --conformance-tests-script.
   --conformance-tests-dest CONFORMANCE_TESTS_DEST
                         Target folder to copy conformance tests of code to (used only if --copy-conformance-tests is set).

{codeplain-0.3.8 → codeplain-0.3.9}/plain2code_telemetry.py

@@ -1,9 +1,10 @@
 """Crash reporting via Sentry.
 
 Only unexpected exceptions are reported (the caller decides which exceptions are
-expected; see EXPECTED_EXCEPTIONS in plain2code.py). Reporting is on by default
-and can be disabled by setting the CODEPLAIN_NO_TELEMETRY environment variable
-to any non-empty value.
+expected; see EXPECTED_EXCEPTIONS in plain2code.py). In production, reporting is
+on by default and can be disabled by setting CODEPLAIN_TELEMETRY to 0, false or
+off. In any other environment it is off unless CODEPLAIN_TELEMETRY is explicitly
+set to 1, true or on.
 """
 
 import os
@@ -20,9 +21,7 @@ from system_config import system_config
 
 SENTRY_DSN = "https://64d0d86b50b34e2dede3e4eaf5142282@o4510793955934208.ingest.us.sentry.io/4511540621213696"
 
-NO_TELEMETRY_ENV_VAR = "CODEPLAIN_NO_TELEMETRY"
-ENVIRONMENT_ENV_VAR = "CODEPLAIN_ENV"
-DEFAULT_ENVIRONMENT = "production"
+TELEMETRY_ENV_VAR = "CODEPLAIN_TELEMETRY"
 
 FLUSH_TIMEOUT_SECONDS = 2
 
@@ -50,10 +49,17 @@ SCRUB_DENYLIST = DEFAULT_DENYLIST + [
 
 
 def telemetry_enabled() -> bool:
-    """Return True if crash reporting should be active."""
-    if os.environ.get(NO_TELEMETRY_ENV_VAR):
-        return False
-    return True
+    """Return True if crash reporting should be active.
+
+    In production it is on unless CODEPLAIN_TELEMETRY disables it.
+    Anywhere else it is off unless CODEPLAIN_TELEMETRY enables it.
+    """
+    setting = os.environ.get(TELEMETRY_ENV_VAR, "").strip().lower()
+
+    if system_config.environment == "production":
+        return setting not in {"0", "false", "off"}
+
+    return setting in {"1", "true", "on"}
 
 
 def initialize_telemetry(**init_overrides: Any) -> bool:
@@ -65,7 +71,7 @@ def initialize_telemetry(**init_overrides: Any) -> bool:
         init_kwargs: dict[str, Any] = dict(
             dsn=SENTRY_DSN,
             release=system_config.client_version,
-            environment=os.environ.get(ENVIRONMENT_ENV_VAR, DEFAULT_ENVIRONMENT),
+            environment=system_config.environment,
             send_default_pii=False,
             server_name="",  # hostname is identifying; don't send it
             default_integrations=False,