Move conformance tests to plain_modules

Author: NejcS

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

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

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

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

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

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

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)
     )

memory_management.py

@@ -3,7 +3,6 @@
 
 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 @@ def fetch_memory_files(memory_folder: str) -> tuple[list[str], dict[str, str]]:
         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

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

module_renderer.py

@@ -1,5 +1,4 @@
 import argparse
-import os
 import threading
 
 from event_bus import EventBus
@@ -48,9 +47,8 @@ def _build_render_context_for_module(
             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 @@ def _render_module(
 
         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 @@ def render_module(self) -> None:
             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))