fix(pipeline): plumb xml2st keep_structs through the shared port contract

[thiagoralves]

Summary

User-reported bug on openplc-web staging: declaring a STRUCT data type breaks the build with Undefined type 'MY_QUEUE' out of strucpp. Same project compiles fine on the desktop editor.

Root cause: xml2st flag drift between platforms. Editor's handleTranspileXMLtoST hardcoded --keep-structs; web's compile-service /generate-st endpoint hardcoded the unflagged invocation. Structs got rewritten to FUNCTION_BLOCKs (matiec's legacy workaround) and strucpp rejected them as type-vs-instance mismatches.

Architecture

The shared port contract carries an array of raw xml2st CLI tokens, not typed booleans per flag. Future xml2st options are a one-line append in runCompilePipeline with no per-platform code changes.

interface TranspileXmlToStArgs {
  xml: string
  xml2stArgs: readonly string[]   // e.g. ['--keep-structs']
}

• Pipeline (shared): always passes xml2stArgs: ['--keep-structs'] for strucpp targets at the single call site in pipeline.ts.
• Editor adapter: passes the array through verbatim to the local xml2st binary (trusted local process).
• Web adapter (companion PR Autonomy-Logic/openplc-web#432): filters the array against KNOWN_XML2ST_FLAGS allowlist, drops + warns on anything unknown.
• compiler-service (companion PR on feat/strucpp-support): accepts xml2st_args: list[str] validated against a server-side allowlist (defence in depth).

Changes

• src/middleware/shared/ports/compiler-platform-port.ts — TranspileXmlToStArgs.xml2stArgs: readonly string[]
• src/backend/shared/compile/pipeline.ts — single call site sets ['--keep-structs']
• src/backend/editor/compiler/compiler-module.ts — handleTranspileXMLtoST takes a third positional extraXml2stArgs: readonly string[], spreads into spawn argv. Internal callers (compileForDebug, compileLibrary) pass ['--keep-structs']
• src/backend/editor/compiler/editor-compiler-platform-port.ts — adapter forwards args.xml2stArgs into the handler

Regression guards

• pipeline.test.ts: asserts the pipeline passes xml2stArgs: ['--keep-structs'].
• editor-compiler-platform-port.test.ts: two new tests verify the adapter forwards a populated array and an empty array verbatim (no silent defaults).

Test plan

• Editor jest green
• tsc --build --force clean
• CI green
• After all three PRs merge → staging deploy → STRUCT-declaring program compiles

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes

  • Ensure consistent preservation of STRUCT declarations during XML→Structured Text transpilation across platforms, preventing loss of struct semantics in downstream compilation.

• Tests

  • Added regression/unit tests to verify transpilation options (struct-preservation flag) are forwarded correctly and remain effective.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: be6430ba-8165-4b2b-a2ed-8e5056e7a2a8

📥 Commits

Reviewing files that changed from the base of the PR and between 4a6b6ab and c955139.

📒 Files selected for processing (6)

• src/backend/editor/compiler/__tests__/editor-compiler-platform-port.test.ts
• src/backend/editor/compiler/compiler-module.ts
• src/backend/editor/compiler/editor-compiler-platform-port.ts
• src/backend/shared/compile/__tests__/pipeline.test.ts
• src/backend/shared/compile/pipeline.ts
• src/middleware/shared/ports/compiler-platform-port.ts

🚧 Files skipped from review as they are similar to previous changes (2)

• src/backend/editor/compiler/editor-compiler-platform-port.ts
• src/backend/shared/compile/tests/pipeline.test.ts

---

Walkthrough

Adds a readonly xml2stArgs array to the shared transpile port and threads it through the pipeline, editor platform port, and compiler handler so callers can append xml2st CLI tokens (e.g., --keep-structs); tests verify editor-side forwarding for non-empty and empty arrays.

Changes

XML-to-ST transpilation xml2stArgs propagation

Layer / File(s)	Summary
Shared port contract (xml2stArgs) src/middleware/shared/ports/compiler-platform-port.ts	TranspileXmlToStArgs adds xml2stArgs: readonly string[] with docs describing how adapters append/validate xml2st CLI tokens.
Compiler handler signature and argv assembly src/backend/editor/compiler/compiler-module.ts	handleTranspileXMLtoST gains extraXml2stArgs and builds xml2st argv as ['--generate-st', generatedXMLFilePath, ...extraXml2stArgs] (no hardcoded --keep-structs).
Handler call sites (debug & lib build Stage 2) src/backend/editor/compiler/compiler-module.ts	Debug compilation and library Stage 2 updated to call handleTranspileXMLtoST with ['--keep-structs'] and adjusted stdout forwarding callback usage.
Editor platform port forwarding + tests src/backend/editor/compiler/editor-compiler-platform-port.ts, src/backend/editor/compiler/__tests__/editor-compiler-platform-port.test.ts	Editor transpileXmlToSt now forwards args.xml2stArgs as the third argument to handlers.handleTranspileXMLtoST. Two tests assert forwarding for ['--keep-structs'] and [], using per-test temp directories.
Pipeline call site and assertion src/backend/shared/compile/pipeline.ts, src/backend/shared/compile/__tests__/pipeline.test.ts	runCompilePipelineInner calls port.transpileXmlToSt with xml2stArgs: ['--keep-structs']. Pipeline test asserts the port was invoked with that array and a function argument.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• Autonomy-Logic/openplc-editor#794: Both PRs touch the XML→ST transpilation plumbing and adapter call sites; #794 refactors the pipeline and adapter plumbing that this change extends.

Suggested labels

enhancement

Suggested reviewers

• vmleroy

Poem

🐰 A rabbit hums near the compile tree,
Passing flags along so structs stay free.
From port to handler the tokens hop,
Empty or full—forwarded on top.
Hooray, the pipeline sings with glee!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: plumbing the xml2st keep_structs flag through the shared port contract to fix platform-specific behavior drift.
Description check	✅ Passed	The description provides a thorough summary, root cause analysis, architecture explanation, detailed change list, and regression test coverage, though the DOD checklist is not completed.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/xml2st-keep-structs-shared-flag

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

[coderabbitai]

Actionable comments posted: 0