Render graphical POUs as readable text on export

.gitattributes

@@ -0,0 +1,17 @@
+# Without this file, line endings are decided by each developer's
+# core.autocrlf. The same commit then checks out differently on different
+# machines, and whoever has it set the other way sees every exported file
+# rewritten the next time they export - a diff of the whole tree that says
+# nothing about what changed.
+* text=auto
+
+# CODESYS writes CRLF, and so does the export. These files are compared
+# against what CODESYS writes and imported back into it, so they check out
+# CRLF everywhere, whatever git is configured to do locally. Only the working
+# tree is pinned; git still stores them normalised, so diffs stay line by
+# line rather than whole-file.
+GraphicalTesting/** text eol=crlf
+tools/ladder/tests/fixtures/codesys/** text eol=crlf
+
+# A .project is a zip. Converting one would corrupt it.
+*.project binary

.github/workflows/ci.yml

@@ -13,6 +13,8 @@ jobs:
       - uses: actions/checkout@v4
       - name: Fail on non-ASCII bytes in src/*.py
         run: python3 tools/ci/check_ascii.py
+      - name: Compile src files with Python 3
+        run: python3 tools/ci/compile_python3.py
 
   ironpython:
     name: ironpython
@@ -30,3 +32,33 @@ jobs:
       - name: Import smoke test with stubbed scriptengine
         shell: pwsh
         run: .\ipy\net45\ipy.exe tools\ci\import_smoke.py
+
+      # The renderers are destined for src/, so they have to pass under the
+      # same interpreter CODESYS embeds - not just under CI's Python 3.
+      - name: Renderer tests under IronPython 2.7
+        shell: pwsh
+        run: |
+          # A native exe's exit code does not halt a pwsh script, so a failure
+          # in the first suite would otherwise be masked by the second passing.
+          .\ipy\net45\ipy.exe tools\ladder\tests\test_ladder.py
+          if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+          .\ipy\net45\ipy.exe tools\ladder\tests\test_fbd.py
+          if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+          .\ipy\net45\ipy.exe tools\ladder\tests\test_export.py
+          if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+          # The only host with both XML backends, so the only place their
+          # equivalence can actually be checked.
+          .\ipy\net45\ipy.exe tools\ladder\tests\test_xmlbackend.py
+          if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+
+  ladder:
+    name: ladder
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Renderer tests under Python 3
+        run: |
+          python3 tools/ladder/tests/test_ladder.py
+          python3 tools/ladder/tests/test_fbd.py
+          python3 tools/ladder/tests/test_export.py
+          python3 tools/ladder/tests/test_xmlbackend.py

.gitignore

@@ -1,5 +1,40 @@
+# CODESYS working files. None of these belong in the repository:
+# a .project is a large binary that every clone then carries for ever, and it
+# and the .opt session files carry device identifiers - serial numbers and
+# gateway addresses - along with the user and machine name in the .~u lock.
+# The template and the exported sources together regenerate the project.
+*.project
+*.opt
+*.~u
+# The template is the exception: it and the exported sources together
+# regenerate the working project, so it is tracked. Its connection label has
+# had the controller address and serial taken out of it - see the commit that
+# tracked it for why clearing the gateway in CODESYS is not enough.
+!GraphicalTesting_template_v1.project
+
+# Review correspondence. Kept beside the checkout, not in it.
+review/
+
+# The export's device and fieldbus xml. 449,000 lines of CR711S and CAN bus
+# descriptions that say nothing about the code under review, and 36 MB that
+# every clone would carry for ever. The application folders are what is
+# tracked; a full export still writes these, they are just not committed.
+GraphicalTesting/*/devices/
+GraphicalTesting/*/communication/
+
+# The staging and backup copies util.py writes beside an export. A locked
+# target leaves one behind, and a stray "git add -A" would sweep the whole
+# export into the repo under it - which is how the device xml got committed
+# once already.
+*.codescribe_staging/
+*.codescribe_backup/
+
 .vscode/
 
+# Claude Code's per-developer tool permissions. Machine-specific paths, and
+# permission grants that should not be inherited by whoever clones the repo.
+.claude/
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]
@@ -160,3 +195,22 @@ cython_debug/
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 #.idea/
+
+# The exported source tree is tracked in full, so none of the generic Python
+# and tooling patterns above may reach into it: a POU or a folder a developer
+# names "lib", "build", "var" or "target" would otherwise be dropped from the
+# export with no warning. Re-include the directories first and then their
+# files - git will not descend into a directory a bare pattern excluded - and
+# re-exclude only the two heavy subtrees that are deliberately left out.
+!GraphicalTesting/**/
+!GraphicalTesting/**
+GraphicalTesting/*/devices/
+GraphicalTesting/*/communication/
+# The re-include above is the last pattern to match inside the export, so it
+# cancels the CODESYS working-file rules at the top of this file as well. Those
+# carry the controller serial and gateway address; exclude them again here.
+GraphicalTesting/**/*.project
+GraphicalTesting/**/*.opt
+GraphicalTesting/**/*.~u
+GraphicalTesting/**/*.codescribe_staging/
+GraphicalTesting/**/*.codescribe_backup/

CHANGELOG.md

@@ -2,9 +2,14 @@
 
 ## Unreleased
 
+- Ladder and Function Block Diagram POUs export a derived `<name>.txt` beside their native xml, holding the declaration and a diagram of each network. Graphical POUs have no textual implementation, so the native xml was the only thing tracked and no change to one could be reviewed in a diff. The declaration is copied from the CODESYS declaration source, keeping comments, pragmas, safety-qualified types and literal spelling; the diagram is derived from a PLCopen export, and its layout comes from how the elements are wired rather than from their coordinates, so moving a block in the editor produces no diff. Networks are numbered as the editor numbers them, read from the native xml beside the rendering: an out-commented or empty network keeps its number and says why it has no diagram, instead of being dropped and renumbering every network after it. A graphical action, transition or method is rendered from its own body, not from the parent POU that its PLCopen export wraps it in. The file is derived and read-only - `Import From Files` dispatches on `.xml` and `.st`, so a `.txt` is ignored by construction and the round trip is unaffected. SFC and CFC POUs are not yet rendered and export as native xml alone. An EXECUTE box shows the inline ST that is its whole body inside the box, below its pins, rather than as an empty rectangle. Where the export carries no plaintext declaration the rendering is rebuilt from the structured interface and says so on its first line, and a variable whose type the export omits reads `UNKNOWN` rather than being assumed to be a `BOOL`. The export summary reports how many POUs were rendered and which were skipped for having no renderable body; a POU whose rendering raises is reported on its own warning line as the export carries on. An equivalent-Structured-Text rendering of the same networks is available from `tools/ladder/write_st.py`, but the export does not write one.
+- An export that produces no files no longer replaces the previous export folder with an empty one; it fails with an explanation and leaves the folder untouched. `Export Lib To Files` on a device project was the trigger: its walker only exports objects directly under the project root, so on a device project it exported nothing and wiped the existing export. That script now also refuses a project with devices up front and points to `Export To Files`.
+- The Library Manager exports its reference list as a read-only `<name>.libraries.txt` (name, version, vendor per line). Library behaviour itself is not exportable, but any bench check of a library needs the version it resolves to - shown where CODESYS reports it, and as the requested constraint (such as `*` for newest) where it does not.
+- The Visualization Manager exports natively as a read-only `<name>.service.txt`. It is exported recursively to take in the target and web visualization settings under it; the global hotkey (key configuration) mapping is in the manager entry itself. Both become reviewable. It is still never imported - importing it raises interactive overwrite dialogs, which is why earlier versions dropped it from the export entirely - and the project template continues to carry the real object.
+
 - Visualisations export as `<name>.vis.xml`. Earlier versions wrote `<name>.xml`, which silently collided with any POU of the same name (a `Main` program plus a `Main` visualisation is common). Old plain `.xml` exports still import correctly; re-exporting once migrates the tracked files.
 - Visualisation service objects (visualisation manager and related service GUIDs) are recognised and no longer exported.
-- `Export To Files` writes the export into a sibling folder named `<project_name>.codescribe_staging` and only swaps it into place once the export completes. Earlier versions deleted the target folder up front, so a locked folder (an open Explorer window, IDE, git client or antivirus) aborted the export immediately and a mid-export crash left the on-disk copy destroyed. If the target folder is locked and cannot be swapped, the staged files are synced into it instead and the export still succeeds; if that also fails, the error dialog reports the staging folder path, so the completed export is preserved.
+- `Export To Files` writes the export into a sibling folder named `<project_name>.codescribe_staging` and only swaps it into place once the export completes. Earlier versions deleted the target folder up front, so a locked folder (an open Explorer window, IDE, git client or antivirus) aborted the export immediately and a mid-export crash left the on-disk copy destroyed. If the target folder is locked and cannot be swapped, the staged files are synced into it instead and the export still succeeds; if that also fails, the error dialog reports the staging folder path, so the completed export is preserved. Syncing also removes files the export did not write, as the swap would have, so a rendering from a previous export is never left beside a newer native xml; any that cannot be removed are named.
 - Device-tree sibling devices (Ethernet, Modbus and fieldbus devices that sit next to `Plc Logic` as direct children of the PLC device) are exported to `<device>/devices/<name>.xml`, one file per top-level device. On import, each tracked device is removed and recreated from its exported xml; devices fixed by the device package (for example `Local_IO` and `HMI` on IFM hardware) cannot be removed and are skipped with a message, with their configuration carried by the project template. A `_NO_EXPORT` folder added as a direct child of the PLC device disables the device-tree export.
 - New `Export Lib To Files` script exports library projects, which keep their objects directly under the project root rather than under a Device. It writes the same on-disk format as `Export To Files`, without the device and application folder levels. Importing a library export back into a project is not yet supported.
 

GraphicalTesting/SafetyPLC/application/EVL.gvl.st

@@ -0,0 +1,7 @@
+(* THIS EVL IS AUTOGENERATED. DO NOT MODIFY THESE ATTRIBUTES. *)
+{attribute 'location' := '16#800' }
+{attribute 'linkalways'}
+{attribute 'qualified_only'}
+VAR_GLOBAL
+
+END_VAR

GraphicalTesting/SafetyPLC/application/EVL.gvl.xml

@@ -0,0 +1,90 @@
+<ExportFile>
+  <StructuredView Guid="{d9b2b2cc-ea99-4c3b-aa42-1e5c49e65b84}">
+<Single xml:space="preserve" Type="{3daac5e4-660e-42e4-9cea-3711b98bfb63}" Method="IArchivable">
+  <Null Name="Profile" />
+  <List2 Name="EntryList">
+    <Single Type="{6198ad31-4b98-445c-927f-3258a0e82fe3}" Method="IArchivable">
+      <Single Name="IsRoot" Type="bool">True</Single>
+      <Single Name="MetaObject" Type="{81297157-7ec9-45ce-845e-84cab2b88ade}" Method="IArchivable">
+        <Single Name="Guid" Type="System.Guid">c92bf834-0a70-4e8b-9367-2d81823c2f23</Single>
+        <Single Name="ParentGuid" Type="System.Guid">4403a37e-f528-4863-8b5f-3c6def9b45a5</Single>
+        <Single Name="Name" Type="string">EVL</Single>
+        <Dictionary Type="{2c41fa04-1834-41c1-816e-303c7aa2c05b}" Name="Properties">
+          <Entry>
+            <Key>
+              <Single Type="System.Guid">0fc3aa33-c9bf-436a-b5e4-fcd0ccb10d58</Single>
+            </Key>
+            <Value>
+              <Single Type="{0fc3aa33-c9bf-436a-b5e4-fcd0ccb10d58}" Method="IArchivable" />
+            </Value>
+          </Entry>
+        </Dictionary>
+        <Single Name="TypeGuid" Type="System.Guid">ffbfa93a-b94d-45fc-a329-229860183b1d</Single>
+        <Array Name="EmbeddedTypeGuids" Type="System.Guid">
+          <Single Type="System.Guid">a9ed5b7e-75c5-4651-af16-d2c27e98cb94</Single>
+        </Array>
+        <Single Name="Timestamp" Type="long">0</Single>
+      </Single>
+      <Single Name="Object" Type="{ffbfa93a-b94d-45fc-a329-229860183b1d}" Method="IArchivable">
+        <Single Name="Interface" Type="{a9ed5b7e-75c5-4651-af16-d2c27e98cb94}" Method="IArchivable">
+          <Single Name="TextDocument" Type="{f3878285-8e4f-490b-bb1b-9acbb7eb04db}" Method="IArchivable">
+            <Array Name="TextLines" Type="{a5de0b0b-1cb5-4913-ac21-9d70293ec00d}">
+              <Single Type="{a5de0b0b-1cb5-4913-ac21-9d70293ec00d}" Method="IArchivable">
+                <Single Name="Id" Type="long">59</Single>
+                <Null Name="Tag" />
+                <Single Name="Text" Type="string">(* THIS EVL IS AUTOGENERATED. DO NOT MODIFY THESE ATTRIBUTES. *)</Single>
+              </Single>
+              <Single Type="{a5de0b0b-1cb5-4913-ac21-9d70293ec00d}" Method="IArchivable">
+                <Single Name="Id" Type="long">60</Single>
+                <Null Name="Tag" />
+                <Single Name="Text" Type="string">{attribute 'location' := '16#800' }</Single>
+              </Single>
+              <Single Type="{a5de0b0b-1cb5-4913-ac21-9d70293ec00d}" Method="IArchivable">
+                <Single Name="Id" Type="long">61</Single>
+                <Null Name="Tag" />
+                <Single Name="Text" Type="string">{attribute 'linkalways'}</Single>
+              </Single>
+              <Single Type="{a5de0b0b-1cb5-4913-ac21-9d70293ec00d}" Method="IArchivable">
+                <Single Name="Id" Type="long">62</Single>
+                <Null Name="Tag" />
+                <Single Name="Text" Type="string">{attribute 'qualified_only'}</Single>
+              </Single>
+              <Single Type="{a5de0b0b-1cb5-4913-ac21-9d70293ec00d}" Method="IArchivable">
+                <Single Name="Id" Type="long">63</Single>
+                <Null Name="Tag" />
+                <Single Name="Text" Type="string">VAR_GLOBAL</Single>
+              </Single>
+              <Single Type="{a5de0b0b-1cb5-4913-ac21-9d70293ec00d}" Method="IArchivable">
+                <Single Name="Id" Type="long">64</Single>
+                <Null Name="Tag" />
+                <Single Name="Text" Type="string"></Single>
+              </Single>
+              <Single Type="{a5de0b0b-1cb5-4913-ac21-9d70293ec00d}" Method="IArchivable">
+                <Single Name="Id" Type="long">65</Single>
+                <Null Name="Tag" />
+                <Single Name="Text" Type="string">END_VAR</Single>
+              </Single>
+              <Single Type="{a5de0b0b-1cb5-4913-ac21-9d70293ec00d}" Method="IArchivable">
+                <Single Name="Id" Type="long">1</Single>
+                <Null Name="Tag" />
+                <Single Name="Text" Type="string"></Single>
+              </Single>
+            </Array>
+          </Single>
+        </Single>
+        <Null Name="NetVarProperties" />
+        <Single Name="ParameterList" Type="bool">False</Single>
+        <Single Name="AddAttributeSubsequent" Type="bool">False</Single>
+      </Single>
+      <Single Name="ParentSVNodeGuid" Type="System.Guid">4403a37e-f528-4863-8b5f-3c6def9b45a5</Single>
+      <Array Name="Path" Type="string">
+        <Single Type="string">SafetyPLC</Single>
+        <Single Type="string">PLC Logic</Single>
+        <Single Type="string">Application</Single>
+      </Array>
+      <Single Name="Index" Type="int">-1</Single>
+    </Single>
+  </List2>
+  <Null Name="ProfileName" />
+</Single>  </StructuredView>
+</ExportFile>

GraphicalTesting/SafetyPLC/application/Library Manager.libraries.txt

@@ -0,0 +1,5 @@
+(* Library references - regenerated by Export To Files; read-only, never imported *)
+ifmR360-3, * (ifm electronic)
+#IoStandard -> IoStandard, 3.5.10.0 (System)
+#CmpSIL2 -> CmpSIL2, 3.5.7.0 (System)
+#3SLicense -> 3SLicense, 3.5.10.0 (3S - Smart Software Solutions GmbH)

GraphicalTesting/SafetyPLC/application/PLC_PRG.st

@@ -0,0 +1,8 @@
+PROGRAM PLC_PRG
+VAR
+
+END_VAR
+
+// --- BEGIN IMPLEMENTATION ---
+
+