{"id":51627923,"url":"https://github.com/mintplayer/mintplayer.polyglot","last_synced_at":"2026-07-13T03:01:23.342Z","repository":{"id":369146529,"uuid":"1288608313","full_name":"MintPlayer/MintPlayer.Polyglot","owner":"MintPlayer","description":"Write code once, transpile to several languages","archived":false,"fork":false,"pushed_at":"2026-07-11T11:54:29.000Z","size":1094,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-07-11T13:12:03.472Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MintPlayer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-07-03T19:18:43.000Z","updated_at":"2026-07-11T11:30:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/MintPlayer/MintPlayer.Polyglot","commit_stats":null,"previous_names":["mintplayer/mintplayer.polyglot"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/MintPlayer/MintPlayer.Polyglot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MintPlayer%2FMintPlayer.Polyglot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MintPlayer%2FMintPlayer.Polyglot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MintPlayer%2FMintPlayer.Polyglot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MintPlayer%2FMintPlayer.Polyglot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MintPlayer","download_url":"https://codeload.github.com/MintPlayer/MintPlayer.Polyglot/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MintPlayer%2FMintPlayer.Polyglot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35408466,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-13T02:00:06.543Z","response_time":119,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-07-13T03:01:22.198Z","updated_at":"2026-07-13T03:01:23.336Z","avatar_url":"https://github.com/MintPlayer.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MintPlayer.Polyglot\n\n\u003e A **cross-SDK transpiler**: write logic once in a small, deliberately-scoped source language (`.pg`)\n\u003e and emit idiomatic, readable code for multiple target SDKs — **C# / .NET**, **TypeScript / JavaScript**,\n\u003e and **Python** (full §3.A surface), plus **PHP** (a **partial** target today — see\n\u003e [Targets are plugins](#targets-are-plugins)), with every target defined as a **pure-JSON plugin**.\n\nPolyglot exists to solve the \"same logic, two languages, kept in sync by hand\" problem (the concrete\nmotivating case: a physics solver living as a hand-maintained twin in C# and TypeScript). Rather than a\ngeneral-purpose \"compile any language to any language\" tool — a known multi-decade trap — Polyglot is\n**faithful-by-default with a published list of relaxations**, and it **refuses** the features that make\ntranspilers balloon (threads, runtime reflection, finalizers, `decimal`, `unsafe`, bit-exact cross-target\nfloats). A differential conformance suite keeps every target's *runtime output* identical, program by\nprogram.\n\n- **Why the name:** a *polyglot* writes in many languages — exactly what the emitter does.\n- **Read first:** [`docs/prd/POLYGLOT_PRD.md`](docs/prd/POLYGLOT_PRD.md) (vision, scope contract,\n  architecture) and [`docs/prd/PLAN.md`](docs/prd/PLAN.md) (the milestone log).\n- **Coming from C# or TypeScript?** Side-by-side construct maps:\n  [`docs/lang/for-csharp-devs.md`](docs/lang/for-csharp-devs.md) ·\n  [`docs/lang/for-typescript-devs.md`](docs/lang/for-typescript-devs.md). The language spec is\n  [`docs/lang/SPEC.md`](docs/lang/SPEC.md).\n\n## A taste\n\n```\n// hello.pg\nimport { print } from \"std.io\"\n\nrecord Point(x: f64, y: f64)\n\nfn dist2(a: Point, b: Point): f64 {\n  let dx = a.x - b.x\n  let dy = a.y - b.y\n  return dx * dx + dy * dy\n}\n\nfn main() {\n  print(\"d2 = ${dist2(Point(3.0, 4.0), Point(0.0, 0.0))}\")\n}\n```\n\n```\npolyglot build hello.pg                      # emits hello.cs + hello.ts (the default pair)\npolyglot build hello.pg --target python     # emits hello.py\npolyglot build hello.pg --target php        # emits hello.php\n```\n\nEach output is idiomatic, readable source for that language — and running all of them prints the same\nbytes.\n\n## Getting the CLI\n\n**Prebuilt (Windows x64):** download `polyglot-win-x64.zip` from\n[GitHub Releases](https://github.com/MintPlayer/MintPlayer.Polyglot/releases) and unzip — it contains\n`polyglot.exe` with its `plugins/` folder beside it (statically linked, zero runtime dependencies). Put\nthe folder on your `PATH`.\n\nEvery release binary ships with a **signed build-provenance attestation** (GitHub artifact\nattestations, SLSA + Sigstore): you can prove your download was built by this repository's release\nworkflow from a specific source commit — not tampered with, not built elsewhere:\n\n```\ngh attestation verify polyglot-win-x64.zip --repo MintPlayer/MintPlayer.Polyglot\n```\n\nThe extracted `polyglot.exe` is attested too, so the same command works on the bare exe. The\nverification output names the exact commit and workflow run that produced the binary.\n\n**From source:**\n\n1. You need **Visual Studio 2026** with the *Desktop development with C++* workload (the projects pin\n   platform toolset **v145**; VS 2022/v143 is not sufficient).\n2. Build the solution:\n\n   ```\n   msbuild MintPlayer.Polyglot.sln /p:Configuration=Debug /p:Platform=x64\n   ```\n\n3. The self-contained CLI lands at `x64\\Debug\\MintPlayer.Polyglot.Cli.exe` with its target plugins in\n   the `plugins\\` folder beside it. Put it on your `PATH` as `polyglot` if you like.\n\nOne-shot verification (build → unit tests → watch gate → differential conformance): `pwsh\nscripts/build-and-test.ps1`. This runs each target's generated output against the C# oracle, so it needs\nthe SDKs of the targets it exercises (at minimum `dotnet` + `node` + `python3` — see below).\n\n## Toolchains \u0026 SDKs\n\nThe `polyglot` CLI itself is a **self-contained native binary with zero runtime dependencies** — you do\nnot need any of the toolchains below just to *transpile*. You only need a target's SDK to **compile/run\nthe code emitted for that target** (and to run that target's leg of the differential conformance suite).\n\n| For | Toolchain / SDK | Official download |\n|---|---|---|\n| **Building the CLI from source** | Visual Studio 2026 — *Desktop development with C++* workload (platform toolset v145) | \u003chttps://visualstudio.microsoft.com/\u003e |\n| **C# / .NET** output | .NET SDK 10+ | \u003chttps://dotnet.microsoft.com/download\u003e |\n| **TypeScript / JS** output | Node.js (LTS) | \u003chttps://nodejs.org/en/download\u003e |\n| **Python** output | Python 3 | \u003chttps://www.python.org/downloads/\u003e |\n| **PHP** output | PHP 8 (Windows builds: the NTS x64 zip) | \u003chttps://www.php.net/downloads\u003e · Windows: \u003chttps://windows.php.net/download/\u003e |\n| **Kotlin** output *(P26, in progress)* | Kotlin command-line compiler `kotlinc` + a JDK 17+ | \u003chttps://kotlinlang.org/docs/command-line.html\u003e · JDK: \u003chttps://adoptium.net/\u003e |\n| **Swift** output *(P26, in progress)* | Swift toolchain (Windows/Linux/macOS) | \u003chttps://www.swift.org/install/\u003e |\n| **Dart** output *(P26, in progress)* | Dart SDK | \u003chttps://dart.dev/get-dart\u003e |\n\nTargets marked *(P26, in progress)* are being added on the `p26-second-wave-targets` branch and are not\nin a shipped release yet; C# / TypeScript / Python are full targets, PHP is a partial target (see\n[Targets are plugins](#targets-are-plugins)).\n\n## Using the CLI\n\n```\npolyglot build \u003cinput.pg\u003e [--target \u003cname\u003e] [--out \u003cdir\u003e] [--root \u003cdir\u003e] [--lib \u003ca,b\u003e] [--watch]\npolyglot check \u003cinput.pg\u003e [--json] [--watch]   # diagnostics only, no output files\npolyglot fmt   \u003cinput.pg\u003e                      # canonical re-print of the source\npolyglot lsp                                   # the language server (spawned by editors, stdio JSON-RPC)\npolyglot install \u003cplugin-dir | npm-name\u003e       # add a target plugin to the user cache\n```\n\n`--watch` keeps the emitted outputs fresh: it rebuilds whenever the input, any transitively imported\n`.pg`, or `pgconfig.json` changes (all configured targets per rebuild). A failed rebuild prints the\ndiagnostics, keeps watching, and never touches the last good outputs.\n\nA `pgconfig.json` next to (or above) your `.pg` files replaces the flags:\n\n```json\n{\n  \"root\": \".\",\n  \"lib\": [\"io\", \"math\"],\n  \"targets\": [\"csharp\", \"typescript\"],\n  \"forbiddenIdentifiers\": { \"*\": [\"temp\"] }\n}\n```\n\n`root` anchors logical imports (`import { a } from \"geometry\"` → `\u003croot\u003e/geometry.pg`), `lib` is the\nambient std prelude (so `print`/`Math` resolve without imports), `targets` is the project's target set —\na bare `polyglot build foo.pg` then emits **all** of them — and `forbiddenIdentifiers` bans names\nproject-wide or per target.\n\n## Targets are plugins\n\nNo language is compiled into the CLI: **a target is one JSON file** (`polyglot-plugin.json` — spec\ntables + emission rules + capabilities + std bindings), validated at load so a malformed or incomplete\nplugin is refused rather than silently miscompiling. The four first-party targets live in\n[`plugins/`](plugins/) and are published to npm:\n\n| Target | Package | Coverage |\n|---|---|---|\n| C# | [`@mintplayer/polyglot-target-csharp`](https://www.npmjs.com/package/@mintplayer/polyglot-target-csharp) | full §3.A |\n| TypeScript | [`@mintplayer/polyglot-target-typescript`](https://www.npmjs.com/package/@mintplayer/polyglot-target-typescript) | full §3.A |\n| Python | [`@mintplayer/polyglot-target-python`](https://www.npmjs.com/package/@mintplayer/polyglot-target-python) | full §3.A |\n| PHP | [`@mintplayer/polyglot-target-php`](https://www.npmjs.com/package/@mintplayer/polyglot-target-php) | **partial** |\n\n\u003e **PHP is a partial target.** C#, TypeScript, and Python each pass the entire differential conformance\n\u003e suite. PHP today covers the base surface plus closures/lambdas, but its plugin still declares several §3.A\n\u003e capabilities unsupported — **exceptions, pattern matching, extension methods, operator overloading,\n\u003e with-expressions, interfaces**, and a few std bindings — so a program using those is **refused with a clear\n\u003e diagnostic** (never miscompiled). Full PHP parity, plus a `run-php.ps1` runtime gate, is milestone **P26\n\u003e (“PHP uplift”)** — see [`docs/prd/PLAN.md`](docs/prd/PLAN.md) §P26.\n\nResolution order: the `plugins/` folder next to the exe → a pgconfig `dependencies` entry\n(`{\"mytarget\": \"file:\u003cdir\u003e\"}`) → the user cache (`%LOCALAPPDATA%\\polyglot\\plugins\\`) → a clean refusal\nnaming the known targets. `polyglot install \u003cname\u003e` fetches a plugin from npm (bare names map to\n`@mintplayer/polyglot-target-\u003cname\u003e`), validates it, and caches it:\n\n```\npolyglot install php               # from npm\npolyglot install path\\to\\plugin    # from a local directory\n```\n\nWriting a new language means writing a JSON file — the PHP backend was added without touching the\ncompiler. **[`docs/plugin-authoring.md`](docs/plugin-authoring.md)** is the guide (manifest anatomy,\nthe rule DSL, validation, testing, publishing), with\n[`plugins/php/polyglot-plugin.json`](plugins/php/polyglot-plugin.json) as the worked example;\n[`docs/design/json-plugins.md`](docs/design/json-plugins.md) records the underlying design.\n\n## Editor support\n\nThe **[MintPlayer Polyglot](https://marketplace.visualstudio.com/items?itemName=mintplayer.polyglot-lang)**\nVS Code extension ships syntax highlighting plus the full language server: live diagnostics,\ngo-to-definition (including into the std library), hover, completion, rename, formatting, per-target\nreserved-name checks, a **live generated-output preview** (\"Show Generated Output\" opens the emitted\nC#/TS/Python beside your `.pg` as you type), and **watch mode** (a status-bar toggle / `polyglot` task\ntype runs `build --watch` in the background with errors in the Problems panel). Highlighting works out\nof the box; the language features need the CLI — set `polyglot.cliPath` or have `polyglot` on `PATH`.\n\n## .NET build integration\n\n[`MintPlayer.Polyglot.MSBuild`](https://www.nuget.org/packages/MintPlayer.Polyglot.MSBuild) (sources in\n[`src/MintPlayer.Polyglot.MSBuild/`](src/MintPlayer.Polyglot.MSBuild/)) makes `dotnet build` transpile\n`.pg` files straight into an ordinary C# project — incremental, clean-aware, non-transitive, no extra\nSDK (the package embeds the native CLI):\n\n```\ndotnet add package MintPlayer.Polyglot.MSBuild\n```\n\nThe `.pg` sources are registered as `Watch` items, so **`dotnet watch build|run` re-transpiles on every\n`.pg` edit** — which is also the watch story inside Visual Studio for .NET hosts (opt out with\n`Watch=\"false\"` metadata or `PolyglotWatch=false`). The end-to-end gate is `tests/msbuild/run-nuget.ps1`.\n\n## Layout\n\n```\nMintPlayer.Polyglot.sln\nsrc/\n  MintPlayer.Polyglot.Core/     # the compiler library (lexer → parser → sema → typed IR → plugin engine)\n  MintPlayer.Polyglot.Cli/      # the `polyglot` CLI (build/check/fmt/lsp/install)\n  MintPlayer.Polyglot.MSBuild/  # the .pg-aware NuGet (assets-only package)\nplugins/                        # the four first-party targets — each one JSON file + npm packaging\neditors/vscode/                 # the VS Code extension (TextMate grammar + LSP client + live preview)\neditors/vs/                     # the Visual Studio VSIX (LSP client)\ntests/\n  MintPlayer.Polyglot.Tests/    # in-process unit tests\n  conformance/                  # differential runtime gates (C#/TS, Python vs the C# oracle)\n  samples/, fidelity/, msbuild/ # sample-compile, fmt round-trip, and NuGet gates\ndocs/\n  prd/                          # PRD + milestone plan\n  lang/                         # SPEC.md, grammar, samples, the Rosetta docs\n  design/                       # subsystem designs (JSON plugins, backend engine, skins, …)\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmintplayer%2Fmintplayer.polyglot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmintplayer%2Fmintplayer.polyglot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmintplayer%2Fmintplayer.polyglot/lists"}