fix: do not emit annotations before unsupported-action comments

[hjotha]

Part of #332.

Fixes #306.

Summary

Unsupported microflow activities are represented as comments in DESCRIBE MICROFLOW output. This PR prevents activity annotations from being emitted before those comments, so the generated MDL remains parseable.

Root cause

The describer emitted object annotations before every formatted activity result. For unsupported activity placeholders the formatted result starts with --, leaving annotations orphaned because comments are not valid microflowStatement targets.

Fix

When a formatted statement begins with a comment marker, emit only the comment and skip emitObjectAnnotations.

Tests

Added traversal coverage for unsupported/comment activity output with preceding activity metadata.

Validation

• make build
• make test
• make lint-go
• make test-integration

Agentic Code Testing

• No new authoring syntax.
• Synthetic regression coverage verifies generated MDL stays parseable.

Test plan

• Unsupported activity comments remain visible.
• No orphan annotations are emitted before comment placeholders.

[github-actions]

AI Code Review

What Looks Good

• Targeted fix: The change precisely addresses the root cause by skipping annotation emission when the formatted statement begins with a comment marker (--), preventing orphaned annotations before unsupported activity placeholders.
• Clear rationale: The added comment explains why annotations must be skipped for comment-formatted statements (grammar only accepts annotations as prefixes of real microflow statements, not comments).
• Test coverage: New unit test TestTraverseFlow_UnsupportedActivitySkipsAnnotations verifies the fix by checking that no @position annotations appear before unsupported-action comments and that the comment itself is present.
• Validation: All specified checks pass (make build, make test, make lint-go, make test-integration).
• No syntax changes: The fix doesn't modify MDL syntax, so MDL syntax design and full-stack consistency checklists don't apply (no new grammar/AST/visitor/executor/LSP changes needed).
• Atomic scope: PR focuses solely on fixing orphaned annotations in DESCRIBE MICROFLOW output for unsupported activities.

Recommendation

Approve the PR. The fix is minimal, well-tested, and resolves the reported issue without introducing side effects or violating project conventions. No changes are needed.

---

Automated review via OpenRouter (Nemotron Super 120B) — workflow source

[github-actions]

AI Code Review

Critical Issues

None found.

Moderate Issues

None found.

Minor Issues

None found.

What Looks Good

• Bug fix correctness: The change correctly addresses the root cause by skipping annotation emission when a statement begins with -- (comment marker), preventing orphaned annotations before unsupported activity placeholders.
• Test coverage:
  • Adds a positive-control bug test (mdl-examples/bug-tests/306-describer-annotations-before-unsupported-comment.mdl) verifying annotations still work for supported activities while unsupported ones emit clean comments.
  • Adds a unit test (TestTraverseFlow_UnsupportedActivitySkipsAnnotations) directly validating the fix for unsupported activities.
  • Both tests are in the correct locations per checklist (bug tests in mdl-examples/bug-tests/, unit tests alongside implementation).
• Validation: PR reports passing make build, make test, make lint-go, and make test-integration.
• Scope: Focused exclusively on the annotation emission bug for unsupported microflow activities (no unrelated changes).
• Code quality:
  • Minimal, localized change (4 lines added) with clear comment explaining the rationale.
  • No duplication of existing logic.
  • Maintains backward compatibility for supported activities.

Recommendation

Approve. The PR correctly fixes the bug with appropriate tests, follows contribution guidelines, and maintains all project standards. No changes needed.

---

Automated review via OpenRouter (Nemotron Super 120B) — workflow source

[ako]

Code Review — PR #307

Overview: One-guard fix in emitActivityStatement to suppress annotations before unsupported-activity comments. Clean and well-motivated.

---

Fix correctness

if strings.HasPrefix(strings.TrimSpace(stmt), "--") {
    *lines = append(*lines, indentStr+stmt)
    return
}

• Correctly intercepts before emitObjectAnnotations, which unconditionally emits @position(x, y) for every object (no nil check, no condition) — so without this guard, every unsupported activity would produce orphaned annotations
• -- is exclusively a comment marker in MDL; no valid statement starts with --, so the prefix check is unambiguous
• strings.TrimSpace is defensive — stmt at this point doesn't carry leading whitespace (indent is prepended separately) — harmless but could be dropped

---

Test correctness

TestTraverseFlow_UnsupportedActivitySkipsAnnotations is valid and would fail without the fix. mkObj("soap") produces a zero-valued BaseMicroflowObject, and emitObjectAnnotations calls:

pos := obj.GetPosition()
*lines = append(*lines, indentStr+fmt.Sprintf("@position(%d, %d)", pos.X, pos.Y))

unconditionally — so @position(0, 0) would be emitted before the comment without the guard. The test correctly catches this.

The check for @position specifically is sufficient: emitObjectAnnotations is a single call that emits all annotation types atomically — if @position is absent, the rest are absent too.

---

Bug test script

The honest note that pure MDL can't reproduce the unsupported-activity path (requires an .mpr with an unknown action type) is appreciated. The positive control (annotated microflow that must still parse correctly after DESCRIBE) is the right substitute — it confirms the annotation-emission path for supported activities is unaffected.

---

Minor

• The fix is general: any new unsupported action type that returns a -- ... statement automatically benefits without any additional changes
• Adding @anchor and @caption to the negative assertions alongside @position would make the test stricter, but since all come from the same emitObjectAnnotations call, the current single check is adequate

---

Overall: Approve. Minimal, correct fix with a meaningful test that would fail without it.

[ako]

@hjotha can you rebase to fix the conflict?

[github-actions]

AI Code Review

What Looks Good

• The PR correctly addresses the root cause: annotations were being emitted before unsupported activity comments (which start with --), causing orphaned annotations that broke MDL re-parsability.
• The fix is minimal and targeted: in cmd_microflows_show_helpers.go, it checks if a statement begins with -- (after trimming space) and skips emitObjectAnnotations in that case.
• Test coverage is strong:
  • New bug test file (mdl-examples/bug-tests/306-describer-annotations-before-unsupported-comment.mdl) provides a positive control showing annotated microflows still work.
  • New unit test (TestTraverseFlow_UnsupportedActivitySkipsAnnotations) directly verifies the fix prevents annotations before unsupported-action comments.
  • The test uses mocks and avoids time.Sleep.
• The PR follows the contribution workflow: it references the related issues (Microflow roundtrip stabilization for large-project audit findings #332, DESCRIBE MICROFLOW emits orphan annotations before unsupported-action comments #306), includes validation steps (make build, make test, etc.), and documents the fix clearly.
• No new MDL syntax is introduced, so syntax design checks don't apply.
• The change is scoped to a single concern (fixing annotation emission for unsupported activities) and doesn't mix unrelated changes.
• Code quality is high: the fix is well-commented, uses standard Go practices, and maintains existing behavior for supported activities.

Recommendation

Approve the PR. The fix is correct, well-tested, and maintains full-stack consistency for the existing DESCRIBE MICROFLOW functionality without requiring changes to other pipeline layers (since it only adjusts output formatting in the executor). No further changes are needed.

---

Automated review via OpenRouter (Nemotron Super 120B) — workflow source