Concept rules in ***plain

⚠️ Breaking Change

This update is not backward compatible.

• Pull the latest code from https://github.com/Codeplain-ai/plain2code_client
• Update any existing ***plain specs to align with the new concept formatting rules
• If you need assistance migrating your specs, contact us at [email protected]

Concept Rules in ***plain

To improve the consistency and clarity of specifications used for code generation, we introduce concept-based definitions with strict formatting rules.

Each definition introduces a single concept, written as:

- :ConceptName: <explanation of the concept>

Concept naming rules

Each concept name must be enclosed in colons (:) at both the beginning and end.

Valid characters for concept name include: Plus sign (+), Minus sign (-), Dot sign (.), Digits (0-9), Uppercase letters (A-Z), Underscore (_), Lowercase letters (a-z).

Examples: :App:, :Tasks:, :ListOfUsers:, :CLI:.

Definition rules

• Each definition must start with the concept name being defined.
• Every concept name must be globally unique.
• Concepts referenced in Functional Requirements, Non-Functional Requirements, Test Requirements, or Acceptance Tests must appear in the Definitions section first.

Migration to *codeplain API keys authentication

*codeplain API keys

This release is introducing migration to internal *codeplain API keys.

⚠️ Breaking Change:
The previous CLAUDE_API_KEY authentication method is no longer supported.

To obtain your new API keys, please contact our support team at [email protected].

Other changes

• Fixed a bug related to parsing plain source templates.

Improved Templating & Isolated Test Environments

Enhanced templating support

Templating is now more flexible and intuitive.

Before:

    - Firstly, ...
{% include "some-template.plain" %}

This required indentation to be managed inside the included file.

Now:

    - Firstly, ...
    - Secondly, {% include "some-template.plain.plain" %}

Templates can now be included inline or indented naturally within the document — indentation is handled automatically, making templates easier to compose and maintain.

Isolated Test Execution

Test scripts for major languages now execute in isolated environments, ensuring clean runs and consistent results.

Supported languages:

• Python
• Golang
• Node.js

This enhancement improves reproducibility and prevents side effects across tests.

Other improvements

• General improvements and bug fixes
• Enhanced observability and logging

Minor Improvements and Bufixes

This release includes bug fixes and minor improvements.

Destination folder for source and conformance test code

With Plain-Git integration for source and conformance test code set in place, we're introducing the ability to utilize and commit the generated code in the existing repositories.

Destination folder for the generated code

You can copy the source code to source code destination folder

Through the plain2code CLI, you can now set --copy-build (bool) argument, telling if you want to copy the source code into destination folder after a successful rendering. By default, this code is copied into dist/ folder, but you can manage this through --build-dest CLI parameter.

You can copy the conformance tests to source code destination folder

Through the plain2code CLI, you can now set --copy-conformance-tests (bool) argument, telling if you want to copy the conformance test code into conformance test destination folder after a successful rendering. By default, this code is copied into dist_conformance_tests/, but you can manage this through --conformance-tests-dest CLI parameter.

Other Changes

• Raising threshold for max conformance test runs to 20, ensuring smoother code generation
• Minor bugfixes

Standardize commit messages, minor improvements and bug fixes

This release standardizes commit messages in build/ and conformance_tests/ folders. Note that this update doesn't break backwards compatibility, so you can continue rendering from the current state.

Also, minor updates and bug fixes were introduced.

Minor Upgrades and Bugfixes

This update includes minor bugfixes for Git conformance tests and adds retry logic for steps that may fail under unstable network conditions. The run.sh scripts in the examples/ folder were also simplified..

Conformance Tests Git Versioning

After adding source code to git, we're now releasing native git integration for conformance tests as well.

Git Integration for Generated Conformance Tests

Native git integration for version-controlled code generation brings you closer to a natural development experience.

Here's what you can do with this feature:

• Automatic Version Control: Your generated code is now automatically versioned in the conformance_tests/ folder
• Commit History: Each successful conformance tests generation creates a commit.
• Easy History Tracking: Simply navigate to your conformance_tests/ folder and run git log to see the complete evolution of your code

Other notable changes

• Removed flag debug to ensure simpler developer experience
• Increased retry counts for conformance tests and unit tests fixing
• Smart truncation of unit tests error message

Retry requests to server on connection errors

Summary

To ensure more robust rendering, improved handling of connection errors to the server has been implemented.

Support for Unrecoverable Exit Codes

Overview

We're introducing a new feature to help identify environment-related issues early in the development process. This feature allows test scripts to signal unrecoverable environment problems through specific exit codes, helping distinguish between code issues and environment setup problems.

Problem

Developers often encounter situations where tests fail not because of the code itself, but due to missing or misconfigured environment dependencies. Common scenarios include:

• Missing database connections (e.g., Docker container not running)
• Unavailable mock servers
• Missing environment variables
• Network connectivity issues

These "it works on my machine" problems can be frustrating and time-consuming to debug.

Solution

Test scripts can now use specific exit codes to indicate unrecoverable environment issues. When these exit codes are encountered, the system will:

• Immediately halt test execution
• Provide a clear error message indicating an environment problem
• Help developers quickly identify and fix environment setup issues

How to setup unrecoverable exit codes in your unit and conformance test scripts

There are two special exit codes on our end at the moment:

• Exit Code 69 (service unavailable) - Use this when there are system configuration problems
• Exit Code 124 (timeout error) - Use this when there's a timeout in test execution.

Please look at run.sh for an example of raising special exit codes.