Add validated OpenPLC export planning

Add versioned OpenPLC target configuration with located-variable and telemetry mappings plus explicit CLI overrides.

Add side-effect-free dry-run readiness for every installed export target and in-memory native OpenPLC project planning.

Author: C-White-1

README.md

@@ -99,8 +99,11 @@ twinforge export project.L5X --target plcopen --output project.xml `
 twinforge export project.L5X --target codesys --output codesys.xml
 twinforge export project.L5X --target openplc --output build\openplc `
   --compile-only
+twinforge export project.L5X --target openplc --output build\openplc `
+  --config openplc-export.json
 twinforge export project.L5X --target automationml --output plant.aml `
   --base-library reference\AutomationML\AutomationML2.10BaseLibraries.aml
+twinforge export project.L5X --target plcopen --output project.xml --dry-run
 ```
 
 `state init` refuses to overwrite an existing path. Validation and inspection
@@ -131,14 +134,21 @@ directory. It currently admits one scheduled program with one RLL routine and
 the tested Boolean, timer, and counter subset; unsupported semantics fail before
 project files are written. `--compile-only` sets that device configuration mode.
 Advanced located-variable and telemetry mappings remain available through the
-Python API pending a validated CLI configuration document.
+Python API and a strict, versioned JSON configuration supplied with `--config`.
+See `examples/OpenPLC/openplc-export.example.json`. Explicit
+`--compile-only` or `--no-compile-only` options override the configured value.
 
 `export --target automationml` writes AutomationML 2.1 / CAEX 3.0 and requires
 the official AutomationML base-library file. An optional `--plcopen-reference`
 links the controller to an existing PLCopen document, while `--xsd` performs
 CAEX validation. File references are made relative to the output document and
 are semantically resolved before anything is written.
 
+Add `--dry-run` to any export target to execute parsing, target planning,
+configuration validation, XSD or semantic validation, and diagnostic reporting
+without writing the requested output. Native OpenPLC planning is performed
+entirely in memory rather than through a disposable project directory.
+
 The example scripts remain useful as focused developer demonstrations of the
 same parser, analysis, and exporter APIs.
 

ROADMAP.md

@@ -150,9 +150,9 @@ The immediate structural priorities are maintained in the
 - [x] Add AutomationML export with semantic references and optional CAEX XSD
 - [ ] Preserve the example scripts as focused demonstrations or thin CLI
   wrappers
-- [ ] Add Pydantic-validated target configuration files and explicit command
-  overrides
-- [ ] Report conversion readiness and unsupported semantics before writing
+- [x] Add versioned OpenPLC target configuration with explicit CLI overrides
+- [ ] Generalize validated configuration to the remaining export targets
+- [x] Add side-effect-free pre-export readiness through `export --dry-run`
   target output
 - [ ] Provide stable process exit codes and optional machine-readable
   diagnostics for automation and CI

examples/OpenPLC/openplc-export.example.json

@@ -0,0 +1,12 @@
+{
+  "schema_version": "1.0",
+  "target": "openplc",
+  "compile_only": true,
+  "locations": {
+    "Enable": "%QX0.0",
+    "Output": "%QX0.1"
+  },
+  "timer_elapsed_locations": {},
+  "counter_accumulator_locations": {},
+  "counter_status_locations": {}
+}

src/twinforge/cli/export_config.py

@@ -0,0 +1,40 @@
+"""Versioned validation models for installed export configuration files."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, ValidationError
+
+
+class ExportConfigurationError(ValueError):
+    """Raised when a target configuration document is unreadable or invalid."""
+
+
+class OpenPLCExportConfig(BaseModel):
+    """Validated options for the runtime-evidenced native OpenPLC target."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    schema_version: Literal["1.0"]
+    target: Literal["openplc"]
+    compile_only: bool = False
+    locations: dict[str, str] = Field(default_factory=dict)
+    timer_elapsed_locations: dict[str, str] = Field(default_factory=dict)
+    counter_accumulator_locations: dict[str, str] = Field(default_factory=dict)
+    counter_status_locations: dict[str, dict[str, str]] = Field(
+        default_factory=dict
+    )
+
+
+def load_openplc_export_config(path: Path) -> OpenPLCExportConfig:
+    """Load one strict, versioned OpenPLC JSON configuration document."""
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+        return OpenPLCExportConfig.model_validate(value)
+    except (OSError, json.JSONDecodeError, ValidationError) as error:
+        raise ExportConfigurationError(
+            f"invalid OpenPLC export configuration '{path}': {error}"
+        ) from error

src/twinforge/cli/l5x_export.py

@@ -26,6 +26,8 @@
     OpenPLCNativeUnsupportedError,
 )
 
+from .export_config import OpenPLCExportConfig, load_openplc_export_config
+
 
 class L5XExportError(RuntimeError):
     """Raised when an installed L5X export operation cannot complete."""
@@ -43,22 +45,42 @@ def export_l5x_target(
     target: str,
     destination: Path,
     schema_path: Path | None,
-    compile_only: bool,
+    compile_only: bool | None,
+    config_path: Path | None,
     base_library_path: Path | None,
     plcopen_reference: Path | None,
+    dry_run: bool,
     stdout: TextIO,
 ) -> None:
     """Export a Controller L5X using one explicit target adapter."""
     try:
         if target == "openplc":
+            config = (
+                load_openplc_export_config(config_path)
+                if config_path is not None
+                else OpenPLCExportConfig(
+                    schema_version="1.0",
+                    target="openplc",
+                )
+            )
             _export_openplc_native(
                 source,
                 destination=destination,
                 schema_path=schema_path,
-                compile_only=compile_only,
+                compile_only=(
+                    compile_only
+                    if compile_only is not None
+                    else config.compile_only
+                ),
+                config=config,
+                dry_run=dry_run,
                 stdout=stdout,
             )
             return
+        if config_path is not None:
+            raise L5XExportError(
+                "--config currently applies only to --target openplc"
+            )
         if target == "automationml":
             _export_automationml(
                 source,
@@ -67,6 +89,7 @@ def export_l5x_target(
                 compile_only=compile_only,
                 base_library_path=base_library_path,
                 plcopen_reference=plcopen_reference,
+                dry_run=dry_run,
                 stdout=stdout,
             )
             return
@@ -78,7 +101,7 @@ def export_l5x_target(
             )
 
         profile = _PROFILES[target]
-        if compile_only:
+        if compile_only is not None:
             raise L5XExportError(
                 "--compile-only applies only to --target openplc"
             )
@@ -101,8 +124,9 @@ def export_l5x_target(
         if schema_path is not None:
             validate_plcopen_xml(result.xml, schema_path)
 
-        destination.parent.mkdir(parents=True, exist_ok=True)
-        destination.write_text(result.xml, encoding="utf-8")
+        if not dry_run:
+            destination.parent.mkdir(parents=True, exist_ok=True)
+            destination.write_text(result.xml, encoding="utf-8")
     except L5XExportError:
         raise
     except (
@@ -124,7 +148,8 @@ def export_l5x_target(
         if profile is PLCopenProfile.STANDARD_201
         else "CODESYS PLCopen XML"
     )
-    stdout.write(f"Exported {label} to {destination}\n")
+    verb = "Ready to export" if dry_run else "Exported"
+    stdout.write(f"{verb} {label} to {destination}\n")
     for diagnostic in [*document.diagnostics, *result.diagnostics]:
         object_name = (
             f" [{diagnostic.object_name}]" if diagnostic.object_name else ""
@@ -140,13 +165,14 @@ def _export_automationml(
     *,
     destination: Path,
     schema_path: Path | None,
-    compile_only: bool,
+    compile_only: bool | None,
     base_library_path: Path | None,
     plcopen_reference: Path | None,
+    dry_run: bool,
     stdout: TextIO,
 ) -> None:
     """Write a semantically validated AutomationML 2.1 document."""
-    if compile_only:
+    if compile_only is not None:
         raise L5XExportError(
             "--compile-only applies only to --target openplc"
         )
@@ -181,10 +207,12 @@ def _export_automationml(
     if schema_path is not None:
         validate_automationml_xml(result.xml, schema_path)
     validate_automationml_references(result.xml, destination)
-    destination.parent.mkdir(parents=True, exist_ok=True)
-    destination.write_text(result.xml, encoding="utf-8")
+    if not dry_run:
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        destination.write_text(result.xml, encoding="utf-8")
 
-    stdout.write(f"Exported AutomationML 2.1 to {destination}\n")
+    verb = "Ready to export" if dry_run else "Exported"
+    stdout.write(f"{verb} AutomationML 2.1 to {destination}\n")
     stdout.write(f"Base library reference: {base_reference}\n")
     if plcopen_path is not None:
         stdout.write(f"PLCopen document reference: {plcopen_path}\n")
@@ -209,6 +237,8 @@ def _export_openplc_native(
     destination: Path,
     schema_path: Path | None,
     compile_only: bool,
+    config: OpenPLCExportConfig,
+    dry_run: bool,
     stdout: TextIO,
 ) -> None:
     """Write the runtime-evidenced native OpenPLC project structure."""
@@ -222,19 +252,40 @@ def _export_openplc_native(
         raise L5XExportError(
             "openplc export currently requires a Controller L5X target; "
             f"found {document.target_type.value}"
-        )
-    result = OpenPLCNativeProjectExporter().export(
+    )
+    exporter = OpenPLCNativeProjectExporter()
+    plan = exporter.plan(
         document.target,
-        destination=destination,
         project_name=document.target_name,
         compile_only=compile_only,
+        locations=config.locations,
+        timer_elapsed_locations=config.timer_elapsed_locations,
+        counter_accumulator_locations=config.counter_accumulator_locations,
+        counter_status_locations=config.counter_status_locations,
     )
-    stdout.write(f"Exported native OpenPLC project to {result.destination}\n")
+    if dry_run:
+        files = tuple(destination / path for path in plan.documents)
+    else:
+        result = exporter.export(
+            document.target,
+            destination=destination,
+            project_name=document.target_name,
+            compile_only=compile_only,
+            locations=config.locations,
+            timer_elapsed_locations=config.timer_elapsed_locations,
+            counter_accumulator_locations=(
+                config.counter_accumulator_locations
+            ),
+            counter_status_locations=config.counter_status_locations,
+        )
+        files = result.files
+    verb = "Ready to export" if dry_run else "Exported"
+    stdout.write(f"{verb} native OpenPLC project to {destination}\n")
     stdout.write(
-        f"Source program {result.source_program_name} was lowered as "
-        f"{result.native_program_name}.\n"
+        f"Source program {plan.source_program_name} was lowered as "
+        f"{plan.native_program_name}.\n"
     )
-    for path in result.files:
+    for path in files:
         stdout.write(f"- {path}\n")
     for diagnostic in document.diagnostics:
         object_name = (

src/twinforge/cli/main.py

@@ -71,8 +71,14 @@ def build_parser() -> argparse.ArgumentParser:
     )
     export_l5x_command.add_argument(
         "--compile-only",
-        action="store_true",
-        help="Set compile-only mode in a native OpenPLC project.",
+        action=argparse.BooleanOptionalAction,
+        default=None,
+        help="Override native OpenPLC compile-only mode.",
+    )
+    export_l5x_command.add_argument(
+        "--config",
+        type=Path,
+        help="Versioned JSON target configuration file.",
     )
     export_l5x_command.add_argument(
         "--base-library",
@@ -84,6 +90,11 @@ def build_parser() -> argparse.ArgumentParser:
         type=Path,
         help="Optional PLCopen document referenced by AutomationML.",
     )
+    export_l5x_command.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Validate and plan the export without writing output.",
+    )
 
     state = commands.add_parser(
         "state",
@@ -147,8 +158,10 @@ def main(
                 destination=arguments.output,
                 schema_path=arguments.xsd,
                 compile_only=arguments.compile_only,
+                config_path=arguments.config,
                 base_library_path=arguments.base_library,
                 plcopen_reference=arguments.plcopen_reference,
+                dry_run=arguments.dry_run,
                 stdout=output,
             )
         elif arguments.state_command == "init":

src/twinforge/targets/openplc/__init__.py

@@ -3,13 +3,15 @@
 from .exporter import OpenPLCExporter
 from .native_project import (
     OpenPLCNativeProjectExporter,
+    OpenPLCNativeProjectPlan,
     OpenPLCNativeProjectResult,
     OpenPLCNativeUnsupportedError,
 )
 
 __all__ = [
     "OpenPLCExporter",
     "OpenPLCNativeProjectExporter",
+    "OpenPLCNativeProjectPlan",
     "OpenPLCNativeProjectResult",
     "OpenPLCNativeUnsupportedError",
 ]