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. 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. 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. Separate the pipeline into explicit passes.
• Use this default flow:

parse -> normalize -> semantic enrichment -> IR -> lowering -> emit -> validate

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

1. 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. 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. 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. 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. 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. 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

src/
  frontends/
  normalization/
  semantic/
  ir/
  lowering/
  emitters/
  diagnostics/
tests/
  fixtures/
  golden/