@game-infra/valibot-to-csharp 0.0.0

package/README.md

@@ -0,0 +1,136 @@
+# @game-infra/valibot-to-csharp
+
+Generate idiomatic C# record types from TypeScript [valibot](https://valibot.dev) schemas.
+
+## Why
+
+We author JSON schemas in TypeScript (in editors and web tooling) but consume that JSON from a .NET game using `System.Text.Json`. Keeping a hand-maintained C# mirror of every `object({...})` is tedious and drifts the moment someone renames a field. This package walks the valibot source with the TypeScript compiler API and emits a `.cs` file whose records deserialise the same JSON, so the mirror is never hand-maintained.
+
+## Install
+
+This package is private and consumed as source from a sibling `game-infra` checkout (see `docs/CONSUMING.md` in the repo root). Add it to your game repo as a linked dependency:
+
+```jsonc
+// pnpm
+"devDependencies": {
+  "@game-infra/valibot-to-csharp": "link:../../../game-infra/packages/valibot-to-csharp"
+}
+
+// npm
+"devDependencies": {
+  "@game-infra/valibot-to-csharp": "file:../../../game-infra/packages/valibot-to-csharp"
+}
+```
+
+## CLI
+
+There is no published dist, so run the CLI straight from the sibling checkout's source with a TS runner such as tsx. Plain `node src/cli.ts` does not work: Node's type stripping refuses to map the `.js` relative import specifiers this repo uses onto their `.ts` sources.
+
+```sh
+npx tsx ../game-infra/packages/valibot-to-csharp/src/cli.ts \
+  --input ./schemas/events.ts \
+  --input ./schemas/common.ts \
+  --output ./Generated \
+  --namespace MyGame.Events
+```
+
+Alternatively, build once inside `game-infra` (`pnpm --filter @game-infra/valibot-to-csharp build`) and run the compiled entry point, which keeps its shebang:
+
+```sh
+node ../game-infra/packages/valibot-to-csharp/dist/cli.js --input ./schemas/events.ts --output ./Generated --namespace MyGame.Events
+```
+
+Flags:
+
+| Flag             | Meaning                                                       |
+| ---------------- | ------------------------------------------------------------- |
+| `--input`, `-i`  | Repeatable. Path to a `.ts` file containing valibot schemas.  |
+| `--output`, `-o` | Output directory for generated `.cs` files.                   |
+| `--namespace`    | C# namespace for emitted types. Defaults to `Generated`.      |
+| `--bundle`       | Write a single bundle `.cs` file with the given name.         |
+| `--union-name`   | Override a union base name. Format: `SchemaConst:CSharpName`. |
+| `--help`, `-h`   | Show usage.                                                   |
+
+## Programmatic
+
+Generate and write files in one call:
+
+```ts
+import { generateToFile } from "@game-infra/valibot-to-csharp";
+
+await generateToFile({
+  inputs: ["./schemas/events.ts"],
+  outputDir: "./Generated",
+  namespace: "MyGame.Events",
+});
+```
+
+Inspect the output without touching disk (handy for embedding into other build pipelines):
+
+```ts
+import { generate } from "@game-infra/valibot-to-csharp";
+
+const result = await generate({
+  inputs: ["./schemas/events.ts"],
+  outputDir: "./Generated",
+  namespace: "MyGame.Events",
+  bundle: true,
+  bundleName: "Events.cs",
+});
+for (const file of result.files) {
+  console.log(file.path, file.content.length);
+}
+```
+
+Go lower-level with the parser and emitter directly:
+
+```ts
+import { emitFileHeader, emitModule, parseFiles } from "@game-infra/valibot-to-csharp";
+
+const module = parseFiles(["./schemas/events.ts"]);
+const emit = emitModule(module, { namespace: "MyGame.Events" });
+const csSource = emitFileHeader(module.notes) + emit.source;
+```
+
+## Supported valibot surface
+
+| valibot                              | C#                                                       |
+| ------------------------------------ | -------------------------------------------------------- |
+| `string()`                           | `string`                                                 |
+| `number()`                           | `double`                                                 |
+| `boolean()`                          | `bool`                                                   |
+| `unknown()`                          | `JsonElement`                                            |
+| `array(X)`                           | `IReadOnlyList<X>`                                       |
+| `record(string(), V)`                | `IReadOnlyDictionary<string, V>`                         |
+| `object({...})`                      | `public sealed record`                                   |
+| `optional(X)` / `nullable(X)`        | Nullable field (`X?`)                                    |
+| `literal('a')`                       | String literal (merged into enums/variant tags)          |
+| `picklist(['a','b'])`                | `[JsonConverter(typeof(JsonStringEnumConverter))] enum`  |
+| `union([literal(...), ...])`         | Enum                                                     |
+| `union([string(), array(string())])` | `StringOrStringList` helper (auto-emitted)               |
+| `union([{type:'A',...}, ...])`       | `[JsonPolymorphic] abstract record` with derived records |
+| `variant('type', [...])`             | Same as discriminated union                              |
+| `pipe(inner, ...validators)`         | `inner` (validators are ignored)                         |
+
+Cross-file imports (relative paths only) are followed automatically so imported schemas land in the same output file. Imports from `node_modules` are not traversed.
+
+## Caveats
+
+- Not evaluated: the generator parses the source and never executes it. Schemas built at runtime (e.g. produced from a function) are invisible to it.
+- String literal kludge: if you write `string('foo')` inside a `union(...)` (a shorthand some schemas use as a literal placeholder), the parser treats it as `literal('foo')` and notes the substitution in the generated file.
+- Unsupported features: `lazy`, `tuple`, `intersect`, `custom` transforms, and non-string record keys. Heterogeneous unions with no common discriminator fall back to `JsonElement`.
+- Nested anonymous objects are named `<ParentType><FieldName>` to avoid collisions with sibling inline types.
+- `DTO` becomes `Dto` in emitted type names (e.g. `EventDefinitionDTOSchema` becomes `EventDefinitionDto`).
+
+## Extension points
+
+- New valibot features: add a node kind to `src/ir.ts`, parse it in `src/parser.ts`, and teach `src/emitter.ts` how to render it. The IR is a closed union, so the compiler points at every switch that needs a new case.
+- Naming: `--union-name` (CLI) / `unionRenames` (API) override the C# base-type name of a union or variant schema without touching the TS source.
+
+## Dependencies
+
+- `@typescript/typescript6`: the classic in-process TypeScript compiler API (`ts.createSourceFile` and friends). TypeScript 7 no longer exposes that API from the `typescript` package root, so the parser uses this compatibility package while the repo compiles with TS 7.
+
+## Consumers
+
+The `*-schemas` contract packages in this repo, and game repos that need C# mirrors of their JSON contracts for .NET clients.

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { generateToFile } from "./generate.js";
+const USAGE = `valibot-to-csharp: generate C# record types from valibot schemas
+
+Usage:
+  valibot-to-csharp --input <file.ts> [--input <file.ts>...] --output <dir> \\
+                    --namespace <Ns> [--bundle <BundleName.cs>] \\
+                    [--union-name <SchemaConst>:<CSharpName>]
+
+Options:
+  --input, -i       TS file containing valibot schemas (repeatable)
+  --output, -o      Output directory for generated .cs files
+  --namespace, -n   C# namespace for emitted types (default: Generated)
+  --bundle          Write a single bundle .cs file with the given name
+  --union-name      Override the C# name of a union/variant schema
+                    (repeatable, format: SchemaConst:CSharpName)
+  --help, -h        Show this help
+`;
+function parseArgs(argv) {
+    const out = { inputs: [], unionRenames: {}, help: false };
+    let i = 0;
+    while (i < argv.length) {
+        const a = argv[i];
+        const next = () => {
+            const v = argv[i + 1];
+            if (v === undefined)
+                throw new Error(`Missing value for ${a}`);
+            i += 2;
+            return v;
+        };
+        switch (a) {
+            case "--help":
+            case "-h":
+                out.help = true;
+                i++;
+                break;
+            case "--input":
+            case "-i":
+                out.inputs.push(next());
+                break;
+            case "--output":
+            case "-o":
+                out.output = next();
+                break;
+            case "--namespace":
+            case "-n":
+                out.namespace = next();
+                break;
+            case "--bundle":
+                out.bundle = next();
+                break;
+            case "--union-name": {
+                const v = next();
+                const sep = v.indexOf(":");
+                if (sep <= 0)
+                    throw new Error(`--union-name expects SchemaConst:CSharpName, got '${v}'`);
+                const key = v.slice(0, sep);
+                const value = v.slice(sep + 1);
+                out.unionRenames[key] = value;
+                break;
+            }
+            default:
+                // Positional arguments are treated as inputs for convenience.
+                if (a.startsWith("-")) {
+                    throw new Error(`Unknown option: ${a}`);
+                }
+                out.inputs.push(a);
+                i++;
+                break;
+        }
+    }
+    return out;
+}
+async function main() {
+    let args;
+    try {
+        args = parseArgs(process.argv.slice(2));
+    }
+    catch (e) {
+        process.stderr.write(`${e.message}\n\n${USAGE}`);
+        process.exit(2);
+    }
+    if (args.help) {
+        process.stdout.write(USAGE);
+        return;
+    }
+    if (args.inputs.length === 0 || !args.output) {
+        process.stderr.write(`Missing required --input and/or --output.\n\n${USAGE}`);
+        process.exit(2);
+    }
+    const absInputs = args.inputs.map((f) => path.resolve(f));
+    for (const f of absInputs) {
+        if (!fs.existsSync(f)) {
+            process.stderr.write(`Input file not found: ${f}\n`);
+            process.exit(2);
+        }
+    }
+    const result = await generateToFile({
+        inputs: absInputs,
+        outputDir: path.resolve(args.output),
+        namespace: args.namespace ?? "Generated",
+        bundle: Boolean(args.bundle),
+        bundleName: args.bundle,
+        unionRenames: args.unionRenames,
+    });
+    const names = result.files.map((f) => path.basename(f.path)).join(", ");
+    process.stdout.write(`Generated ${result.files.length} file(s) in ${path.resolve(args.output)}: ${names}\n`);
+}
+main().catch((e) => {
+    process.stderr.write(`Error: ${e.stack ?? e}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/emitter.d.ts

@@ -0,0 +1,68 @@
+import type { SchemaModule } from "./ir.js";
+/**
+ * Options accepted by {@link emitModule}.
+ *
+ * @example
+ * ```ts
+ * import type { EmitOptions } from "@game-infra/valibot-to-csharp";
+ *
+ * const opts: EmitOptions = {
+ *   namespace: "MyGame.Events",
+ *   unionRenames: new Map([["ActionSchema", "GameAction"]]),
+ * };
+ * ```
+ */
+export interface EmitOptions {
+    namespace: string;
+    /** Optional renames for union/variant base types. Keyed by source const name. */
+    unionRenames?: Map<string, string>;
+}
+/**
+ * Result of {@link emitModule}.
+ *
+ * @example
+ * ```ts
+ * import { emitModule, parseFiles } from "@game-infra/valibot-to-csharp";
+ * import type { EmitResult } from "@game-infra/valibot-to-csharp";
+ *
+ * const result: EmitResult = emitModule(parseFiles(["./schemas/events.ts"]), {
+ *   namespace: "MyGame.Events",
+ * });
+ * console.log(result.source);
+ * ```
+ */
+export interface EmitResult {
+    /** Full C# source body (namespace + types). */
+    source: string;
+    /** True if any StringOrStringList helper was referenced. */
+    usesStringOrStringList: boolean;
+}
+/**
+ * Turn a {@link SchemaModule} into a C# source file body. The caller wraps
+ * this with the using-block header (see {@link emitFileHeader}) and writes it
+ * to disk.
+ *
+ * @example
+ * ```ts
+ * import { emitFileHeader, emitModule, parseFiles } from "@game-infra/valibot-to-csharp";
+ *
+ * const module = parseFiles(["./schemas/events.ts"]);
+ * const emit = emitModule(module, { namespace: "MyGame.Events" });
+ * const csFile = emitFileHeader(module.notes) + emit.source;
+ * ```
+ */
+export declare function emitModule(module: SchemaModule, opts: EmitOptions): EmitResult;
+/**
+ * Render the file-level header: auto-generated banner + using-block. Split out
+ * so callers that want to embed the emitter output in larger files can skip it.
+ *
+ * @example
+ * ```ts
+ * import { emitFileHeader } from "@game-infra/valibot-to-csharp";
+ *
+ * const header = emitFileHeader([]);
+ * // "// <auto-generated>..." plus the System.Text.Json using-block
+ * ```
+ */
+export declare function emitFileHeader(notes: string[]): string;
+//# sourceMappingURL=emitter.d.ts.map

package/dist/emitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emitter.d.ts","sourceRoot":"","sources":["../src/emitter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAIV,YAAY,EAGb,MAAM,SAAS,CAAC;AAGjB;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,iFAAiF;IACjF,YAAY,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACpC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,UAAU;IACzB,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,sBAAsB,EAAE,OAAO,CAAC;CACjC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,WAAW,GAAG,UAAU,CA0B9E;AAgBD;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAgBtD"}