Universal Code Converter

Build or refine the converter as a staged translation pipeline. Optimize for semantic fidelity, diagnostics, and incremental delivery instead of "convert everything" claims.

Run This Workflow

1. 1. Clarify the scope.

- Capture the source language, target language, runtime constraints, supported constructs, and quality bar. - Ask for or extract at least 3 representative snippets before designing the pipeline. - Define what "done" means: compilable output, behavior-preserving output, migration scaffold, or partial assisted conversion.

1. 2. Verify the parser frontend.

- Confirm the required Tree-sitter grammars exist and are actively usable. - Prefer official prebuilt bindings or grammar packages for the first frontend probe. Compile grammars manually only when official artifacts are missing or the task needs grammar changes. - Inspect actual node types and field names before hardcoding visitors. - Capture one reusable parser-probe artifact from real fixtures: root node type, critical field names, and one query/capture example. Keep it in tests or fixtures so later work does not repeat manual spelunking. - If Tree-sitter is part of the plan, run one incremental reparse check with old_tree to prove the grammar is usable as an editing frontend. Treat this as a capability check, not a brittle microbenchmark. - Treat Tree-sitter as a concrete syntax tree frontend with incremental parsing, not as a full semantic compiler.

1. 3. Separate the pipeline into explicit passes.

- Use this default flow:

CODEBLOCK0

- Keep normalization separate from semantic analysis.
- Keep shared IR logic separate from pair-specific lowering rules.
- Keep code formatting separate from translation logic.

1. 4. Design the IR around semantics, not surface syntax.

- Model declarations, scopes, bindings, literals, calls, control flow, imports, types, and diagnostics. - Represent lossy or unsupported constructs explicitly with diagnostic nodes or status flags. - Remove syntax sugar early when it simplifies downstream lowering.

1. 5. Implement a narrow vertical slice first.

- Start with one source-target pair. - Start with modules, functions, parameters, literals, identifiers, returns, calls, and simple conditionals. - Add tests for each slice before adding more syntax.

1. 6. Handle semantic gaps intentionally.

- Classify every feature as one of: direct mapping, desugaring, runtime helper, manual rewrite required, or unsupported. - Emit warnings for behavior changes or lossy rewrites. - Never silently drop exceptions, mutability rules, async semantics, or type expectations.

1. 7. Generate target code from a structured model.

- Prefer a typed target-language model or emitter API over raw string replacement. - Centralize naming, escaping, and indentation in the emitter layer. - Preserve comments or source maps only when the task explicitly requires them.

1. 8. Validate the output at multiple levels.

- Validate frontend assumptions separately from lowering assumptions. - Reparse representative source fixtures and assert the parser-probe contract stays stable. - Reparse the generated code. - Compile or type-check the generated code when tooling is available. - Run fixture-based execution tests for behavior-preserving conversions. - Include at least one explicit failure-path fixture that must emit diagnostics. - Snapshot IR and emitted output for regression coverage.

1. 9. Deliver a bounded result.

- Return the supported feature matrix, known gaps, assumptions, warnings, and next steps. - Say clearly when the result is a scaffold, partial converter, or production-ready slice.

Produce These Deliverables

• - For architecture requests, return: scope, pipeline, IR outline, feature mapping taxonomy, validation plan, and risk list.
• For implementation requests, code the smallest working slice first, add executable tests with it, and record the exact frontend dependency/version used for the parser probe.
• For review requests, prioritize semantic drift, unsupported constructs, parser-shape assumptions, and missing validation.

Read Additional References Only When Needed

• - Read references/architecture-blueprint.md for module layout, feature mapping taxonomy, and IR design prompts.
• Read references/validation-checklist.md for test strategy, regression gates, and release criteria.

Apply These Guardrails

• - Do not call the converter "universal" unless a supported-language and supported-feature matrix exists.
• Do not equate CST shape with program meaning.
• Do not put all translation rules in one transformer file.
• Do not promise idiomatic target code before correctness and diagnostics exist.
• Do not add a new language pair without representative fixtures and validation.

Start With This Repo Shape

CODEBLOCK1